Create Session

Create a sandbox session and return a session token, provider, and base sandbox URL. Set session_kind to browser to start a browser-backed session instead of a standard command/code sandbox. Set queue_if_full to true to queue the request instead of failing when runner capacity is temporarily unavailable.

POST /api/v1/sandbox/sessions

Python (SDK)

Python

from mka1 import SDK


with SDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as sdk:

    res = sdk.sandbox.create(session_id="demo-python-20260316", user_id="demo-user", session_kind="standard", ttl_seconds=600, sandbox_features=[], queue_if_full=False)

    # Handle response
    print(res)

200

{
  "session": {
    "session_id": "demo-python-20260316",
    "user_id": "demo-user",
    "status": "idle",
    "session_kind": "standard",
    "ttl_seconds": 600,
    "workspace_expires_at": "2026-03-23T20:40:00Z",
    "sandbox_features": [],
    "api_key_id": null,
    "permissions": [],
    "runner_id": "runner-usw2a-01",
    "runner_url": "http://runner:8010",
    "runner_zone": "us-west-2a",
    "created_at": "2026-03-16T20:40:00Z",
    "updated_at": "2026-03-16T20:40:02Z"
  },
  "session_token": "sandbox_test_20260316_4f9c2b1a",
  "sandbox_url": "http://10.0.3.19:8010/v1/sandboxes/demo-python-20260316",
  "provider": "runner-firecracker"
}

Authorizations

Authorization · string · header · required

Gateway auth: send Authorization: Bearer <mka1-api-key>. For multi-user server-side integrations, you can also send X-On-Behalf-Of: <external-user-id>.

Headers

X-On-Behalf-Of · string

Optional external end-user identifier forwarded by the API gateway.

Body

application/json

session_id · string · required

session_key · string | null

user_id · string · default: demo-user

session_kind · enum<string> · default: standard

Available options: standard, browser

ttl_seconds · integer · default: 600

Required range: x >= 1

sandbox_features · enum<string>[]

Available options: python, git, claude-code

memory_mounts · MemoryMount · object[]

Show child attributes

queue_if_full · boolean · default: false

Response

200

application/json

Successful Response

session · SessionRecord · object · required

Show child attributes

session_token · string · required

sandbox_url · string | null

provider · enum<string> | null

Available options: in-memory, runner-process, runner-docker, runner-firecracker