> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Run code in ephemeral or durable sandboxes for custom tools and agent workbenches.

The **Sandbox** API runs code in isolated environments. Use an **ephemeral** run to preview a script once, or a **durable session** when you need a longer-lived VM (for example while building or debugging a custom tool).

Agents can also use native workbench tools; this page covers the REST surface. See also [Tools](/guides/tools) (custom tools) and [Native tools](/guides/native-tools).

## Ephemeral vs durable

| | Ephemeral | Durable session |
| - | - | - |
| Lifecycle | Create → run → kill in one call | Create session, execute many times, then delete |
| Best for | Script previews before `POST /tools` | Longer workbenches, iterative execute |
| Billing | One-shot | Session lifetime |

## API endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/v1/sandbox/ephemeral` | Run code in an ephemeral sandbox |
| `POST` | `/api/v1/sandbox/sessions` | Create a durable session |
| `GET` | `/api/v1/sandbox/sessions/{id}` | Session status |
| `DELETE` | `/api/v1/sandbox/sessions/{id}` | End session |
| `POST` | `/api/v1/sandbox/sessions/{id}/execute` | Execute in a session |
| `GET` | `/api/v1/sandbox/threads/{threadId}` | Thread-linked sandbox info |
| `POST` | `/api/v1/sandbox/threads/{threadId}/start` | Prepare/resume agent-thread sandbox |

### Example: ephemeral run

```bash theme={null}
curl -X POST "https://flowra.dev/api/v1/sandbox/ephemeral" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "javascript",
    "source": "return { ok: true, n: 1 + 1 };"
  }'
```

Required fields: `language` (`javascript` | `python`) and `source` (script text). Optional: `state`, `timeoutMs` (default 8000, max 20000). See **SandboxEphemeralDto** and **CreateSandboxSessionDto** in the [API reference](/api-reference).

### SDK

```ts theme={null}
await flowra.sandbox.runEphemeral({
  language: 'javascript',
  source: 'return { ok: true, n: 1 + 1 };',
});
```

```python theme={null}
flowra.sandbox.run_ephemeral({
    "language": "javascript",
    "source": "return { ok: true, n: 1 + 1 };",
})
```

Durable sessions: `sandbox.createSession` / `create_session`, `execute`, `getSession` / `get_session`, `releaseSession` / `release_session`.

## Related

* [Tools](/guides/tools) — Create custom tools after a successful sandbox preview
* [Browser sessions](/guides/browser-sessions) — Live browser runtime (separate from code sandbox)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.