Sandbox - Flowra

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 (custom tools) and 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

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.

SDK

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

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.

Tools — Create custom tools after a successful sandbox preview
Browser sessions — Live browser runtime (separate from code sandbox)