Sandbox Instances

The Sandbox Instances API is used to create, query, and manage the sandbox lifecycle, and to query sandbox logs and resource metrics.

Create a Sandbox

Description

Creates a sandbox instance from the specified template.

Request Path

POST /sandboxes

Request Parameters

Parameter	Type	Required	Description
templateID	string	Yes	Template ID or template name
timeout	integer	No	Sandbox timeout in seconds. Defaults to 15
autoPause	boolean	No	Whether to automatically pause the sandbox after timeout. Defaults to false
secure	boolean	No	Whether to enable secure mode for sandbox system communication
allow_internet_access	boolean	No	Whether the sandbox can access the public internet. When false, this is equivalent to denying 0.0.0.0/0 outbound traffic in the network configuration
network.allowPublicTraffic	boolean	No	Whether the sandbox's public access address allows public traffic. Defaults to true
network.allowOut	string[]	No	CIDR or IP list allowed for outbound access
network.denyOut	string[]	No	CIDR or IP list denied for outbound access
network.maskRequestHost	string	No	Host mask used by sandbox requests
metadata	object	No	Custom metadata. Keys and values are strings
envVars	object	No	Environment variables injected when the sandbox starts
mcp	object	No	MCP configuration
injections	array	No	Inline secret injection rules. Up to 20 items
resources	array	No	External resources prepared and mounted before the sandbox starts. Up to 20 items

resources currently supports github_repository:

Parameter	Type	Required	Description
resources[].type	string	Yes	Resource type. Use github_repository for GitHub repository resources
resources[].url	string	Yes	GitHub repository URL. HTTPS URLs and GitHub SSH-style URLs such as git@github.com:owner/repo.git are supported. The platform normalizes them to HTTPS
resources[].mount_path	string	Yes	Absolute mount path for the repository contents inside the sandbox
resources[].authorization_token	string	Yes	GitHub token used to access the repository. Multiple GitHub repository resources in the same sandbox currently must use the same token

Response Fields

Field	Type	Description
templateID	string	Template ID used to create the sandbox
sandboxID	string	Sandbox instance ID
alias	string	Template alias
envdVersion	string	envd version inside the sandbox
envdAccessToken	string	Token used to access envd inside the sandbox
trafficAccessToken	string	Token required to access sandbox proxy traffic
domain	string	Sandbox traffic access domain

Request Example

curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateID": "base",
    "timeout": 300,
    "metadata": {
      "project": "demo"
    },
    "envVars": {
      "APP_ENV": "dev"
    }
  }'

Response Example

{
  "templateID": "base",
  "sandboxID": "sbx_123456",
  "envdVersion": "0.1.0",
  "envdAccessToken": "envd-token",
  "trafficAccessToken": "traffic-token",
  "domain": "sbx_123456.example.sufyapi.com"
}

List Sandboxes

Description

Lists sandboxes under the current account. GET /v2/sandboxes is recommended because it supports state filtering and pagination.

Request Path

GET /v2/sandboxes

Compatible path:

GET /sandboxes

Request Parameters

Parameter	Type	Required	Description
metadata	string	No	Metadata filter, for example user=abc&app=prod. Keys and values must be URL-encoded
state	string[]	No	Sandbox state filter. Available values: running, paused
nextToken	string	No	Pagination cursor
limit	integer	No	Number of items per page. Range: 1 to 100. Defaults to 100

Response Fields

Returns an array of sandbox objects:

Field	Type	Description
templateID	string	Template ID used to create the sandbox
sandboxID	string	Sandbox instance ID
alias	string	Template alias
startedAt	string	Sandbox start time
endAt	string	Sandbox expiration time
cpuCount	integer	CPU core count
memoryMB	integer	Memory size in MiB
diskSizeMB	integer	Disk size in MiB
metadata	object	Custom metadata
state	string	Sandbox state. Available values: running, paused
envdVersion	string	envd version inside the sandbox
executionId	string	Sandbox execution ID
uid	string	Sufy user UID

Request Example

curl -G "$SUFY_SANDBOX_API_URL/v2/sandboxes" \
  -H "X-API-Key: $SUFY_API_KEY" \
  --data-urlencode "state=running" \
  --data-urlencode "limit=20"

Get Sandbox Details

Request Path

GET /sandboxes/{sandboxID}

Path Parameters

Parameter	Type	Required	Description
sandboxID	string	Yes	Sandbox instance ID

Response Fields

Field	Type	Description
templateID	string	Template ID used to create the sandbox
sandboxID	string	Sandbox instance ID
startedAt	string	Sandbox start time
endAt	string	Sandbox expiration time
cpuCount	integer	CPU core count
memoryMB	integer	Memory size in MiB
diskSizeMB	integer	Disk size in MiB
metadata	object	Custom metadata
state	string	Sandbox state
envdVersion	string	envd version inside the sandbox
envdAccessToken	string	Token used to access envd inside the sandbox
domain	string	Sandbox traffic access domain

Delete a Sandbox

Description

Terminates and deletes the specified sandbox.

Request Path

DELETE /sandboxes/{sandboxID}

Path Parameters

Parameter	Type	Required	Description
sandboxID	string	Yes	Sandbox instance ID

Response Fields

Returns 204 No Content on success, with no response body.

Pause a Sandbox

Request Path

POST /sandboxes/{sandboxID}/pause

Returns 204 No Content on success.

Resume a Sandbox

Request Path

POST /sandboxes/{sandboxID}/resume

Request Parameters

Parameter	Type	Required	Description
timeout	integer	No	Timeout after resume, in seconds. Defaults to 15
autoPause	boolean	No	Deprecated. Whether to automatically pause after timeout

Returns sandbox connection information on success. The fields are the same as the create sandbox response.

Connect to a Sandbox

Description

Gets sandbox connection information. If the sandbox is paused, it is resumed first. If the sandbox is already running, only its TTL is extended.

Request Path

POST /sandboxes/{sandboxID}/connect

Request Parameters

Parameter	Type	Required	Description
timeout	integer	Yes	Timeout from the current time, in seconds

Returns sandbox connection information on success. The fields are the same as the create sandbox response.

Set Sandbox Timeout

Request Path

POST /sandboxes/{sandboxID}/timeout

Request Parameters

Parameter	Type	Required	Description
timeout	integer	Yes	Timeout from the current time, in seconds

Returns 204 No Content on success.

Extend Sandbox Lifetime

Request Path

POST /sandboxes/{sandboxID}/refreshes

Request Parameters

Parameter	Type	Required	Description
duration	integer	No	Extension duration in seconds. Maximum: 3600

Returns 204 No Content on success.

Query Sandbox Logs

Request Path

GET /sandboxes/{sandboxID}/logs

Request Parameters

Parameter	Type	Required	Description
start	integer	No	Log start timestamp in milliseconds
limit	integer	No	Number of log entries to return

Response Fields

Field	Type	Description
logs[].timestamp	string	Log timestamp
logs[].line	string	Log content
logEntries[].timestamp	string	Structured log timestamp
logEntries[].level	string	Log level
logEntries[].message	string	Log message
logEntries[].fields	object	Structured fields

Query Sandbox Metrics

Request Path

GET /sandboxes/{sandboxID}/metrics

Request Parameters

Parameter	Type	Required	Description
start	integer	No	Start Unix timestamp in seconds
end	integer	No	End Unix timestamp in seconds

Response Fields

Returns an array of metric objects:

Field	Type	Description
timestampUnix	integer	Metric timestamp, as a Unix timestamp in seconds
cpuCount	integer	CPU core count
cpuUsedPct	number	CPU usage percentage
memUsed	integer	Used memory in bytes
memTotal	integer	Total memory in bytes
diskUsed	integer	Used disk space in bytes
diskTotal	integer	Total disk space in bytes

Batch Query Sandbox Metrics

Request Path

GET /sandboxes/metrics

Request Parameters

Parameter	Type	Required	Description
sandbox_ids	string[]	Yes	Sandbox ID list, passed as a single comma-separated query parameter. Up to 100 IDs

Request Example

curl -G "$SUFY_SANDBOX_API_URL/sandboxes/metrics" \
  -H "X-API-Key: $SUFY_API_KEY" \
  --data-urlencode "sandbox_ids=sbx_123456,sbx_789012"

Response Fields

Returns a metrics object keyed by sandbox ID:

Field	Type	Description
sandboxes	object	Sandbox metrics map, keyed by sandbox ID
sandboxes.<sandboxID>.timestampUnix	integer	Metric timestamp, as a Unix timestamp in seconds
sandboxes.<sandboxID>.cpuCount	integer	CPU core count
sandboxes.<sandboxID>.cpuUsedPct	number	CPU usage percentage
sandboxes.<sandboxID>.memUsed	integer	Used memory in bytes
sandboxes.<sandboxID>.memTotal	integer	Total memory in bytes
sandboxes.<sandboxID>.diskUsed	integer	Used disk space in bytes
sandboxes.<sandboxID>.diskTotal	integer	Total disk space in bytes

Related Documents

• API Overview
• Templates
• Secret Injection
• Sandbox Runtime