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

Request bodies: SandboxEphemeralDto, CreateSandboxSessionDto — see API reference — Sandbox.

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