> ## 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",
    "code": "return { ok: true, n: 1 + 1 };"
  }'
```

Request bodies: **SandboxEphemeralDto**, **CreateSandboxSessionDto** — see [API reference — Sandbox](/api-reference).

## Related

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