Acquire a local sandbox

Initializes a specialized Virtual Machine environment (Local Sandbox) that hosts multiple interconnected MCP servers. Optionally specify a benchmark (e.g., ‘Toolathlon’) to configure the sandbox. IMPORTANT: The benchmark parameter may affect BOTH (1) the initial data environment (e.g., preloaded data or pre-configured state for supported servers) AND (2) the MCP server implementation itself — some servers may be routed to a benchmark-specific MCP server with potentially different tools or behaviors.

POST /local-sandbox

Acquire a local sandbox

cURL

curl --request POST \
  --url https://api.klavis.ai/local-sandbox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "server_names": [
    "filesystem"
  ],
  "benchmark": "MCP_Atlas",
  "test_account_email": "<string>",
  "ttl_seconds": 7200
}
'

201

{
  "local_sandbox_id": "<string>",
  "servers": [
    {
      "id": "<string>",
      "server_name": "<string>",
      "mcp_server_url": "<string>",
      "status": "idle",
      "benchmark": "<string>",
      "updated_at": "<string>",
      "metadata": {},
      "auth_data": {},
      "tags": [
        "<string>"
      ]
    }
  ],
  "status": "idle",
  "benchmark": "<string>",
  "message": "<string>"
}

Authorizations

Authorization · string · header · required

Your Klavis AI API key.

Body

application/json

server_names · enum<string>[] string · required

List of MCP servers to acquire, or 'ALL' for all available local servers

Supported MCP servers for local sandboxing. These are typically stateless or local-only servers.

Available options: filesystem, git, terminal, desktop-commander, arxiv, excel, word, powerpoint, code-executor, code-runner, pdf-tools, google_cloud, poste_email_toolathlon, canvas, localmemory, playwright

benchmark · enum<string> | null

Optional benchmark to configure the local sandbox. NOTE: This parameter may affect BOTH (1) the initial data environment (preloaded data for supported servers) AND (2) the MCP server implementation (some servers are routed to a benchmark-specific MCP server with potentially different tools or behaviors).

Available options: MCP_Atlas, Toolathlon, MCP_Mark

test_account_email · string | null

Specific test account email

ttl_seconds · integer | null · default: 7200

TTL in seconds. The local sandbox will be automatically released after this duration. Default: 7200 (2 hours). Min: 60 (1 minute). Max: 86400 (24 hours). Set to null to disable auto-release.

Required range: 60 <= x <= 86400

Response

201

application/json

Successful Response

local_sandbox_id · string · required

Unique identifier for the entire local sandbox environment

servers · LocalSandboxServerItem · object[] · required

List of interconnected MCP servers running in this sandbox

Show child attributes

status · enum<string> | null

Overall status of the local sandbox environment

Available options: idle, occupied, error

benchmark · string | null

Benchmark environment configuration used for the local sandbox

message · string | null

Status message