Skip to main content
POST
/
local-sandbox
Acquire a local sandbox
curl --request POST \
  --url https://api.klavis.ai/local-sandbox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "server_names": [],
  "test_account_email": "<string>",
  "ttl_seconds": 7200
}
'
import requests

url = "https://api.klavis.ai/local-sandbox"

payload = {
"server_names": [],
"test_account_email": "<string>",
"ttl_seconds": 7200
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({server_names: [], test_account_email: '<string>', ttl_seconds: 7200})
};

fetch('https://api.klavis.ai/local-sandbox', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({server_names: [], test_account_email: '<string>', ttl_seconds: 7200})
};

fetch('https://api.klavis.ai/local-sandbox', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
{
  "local_sandbox_id": "<string>",
  "servers": [
    {
      "id": "<string>",
      "server_name": "<string>",
      "mcp_server_url": "<string>",
      "benchmark": "<string>",
      "updated_at": "<string>",
      "metadata": {},
      "auth_data": {},
      "tags": [
        "<string>"
      ]
    }
  ],
  "benchmark": "<string>",
  "message": "<string>"
}
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}

Authorizations

Authorization
string
header
required

Your Klavis AI API key.

Body

application/json
server_names
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

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

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