---
title: "Acquire a local sandbox"
method: POST
path: "/local-sandbox"
tags: ["local-sandbox"]
---

# Acquire a local sandbox

`POST /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.

## Request body

- AcquireLocalSandboxRequest
  - `server_names` union, required — List of MCP servers to acquire, or 'ALL' for all available local servers
    - LocalSandboxMCPServer[]
    - 'ALL'
  - `benchmark` 'MCP_Atlas' | 'Toolathlon' | 'MCP_Mark' — Supported benchmarks for sandbox initial environment
  - `test_account_email` string, nullable — Specific test account email
  - `ttl_seconds` integer, nullable — 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.

## Response `201`

Successful Response

- AcquireLocalSandboxResponse
  - `local_sandbox_id` string, required — Unique identifier for the entire local sandbox environment
  - `status` 'idle' | 'occupied' | 'error' — Status of a sandbox instance - matches database enum
  - `benchmark` string, nullable — Benchmark environment configuration used for the local sandbox
  - `servers` LocalSandboxServerItem[], required — List of interconnected MCP servers running in this sandbox
    - `server_name` string, nullable — Name of the MCP server
    - `id` string, required — Unique identifier for this specific server instance within the sandbox
    - `mcp_server_url` string, nullable — URL to connect to this specific MCP server instance
    - `status` 'idle' | 'occupied' | 'error' — Status of a sandbox instance - matches database enum
    - `benchmark` string, nullable — Benchmark environment configuration
    - `updated_at` string, nullable — Last update timestamp
    - `metadata` object, nullable — Additional metadata for the sandbox
    - `auth_data` object, nullable — Authentication data for the sandbox
    - `tags` string[], nullable — Sandbox tags
  - `message` string, nullable — Status message

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/klavis-ai/apis/klavis-ai-https-www-klavis-ai.md) · [All operations](https://skmtc.net/klavis-ai/apis/klavis-ai-https-www-klavis-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/klavis-ai/klavis-ai-https-www-klavis-ai/revisions/1f05ced7280f/schema)