Appearance
Sandbox Runtime
The Sandbox Runtime API is provided by envd inside the sandbox. It is used to get runtime status, environment variables, and resource metrics, and it also serves as the access point for the Processes API and File System API.
Unlike region-level Open APIs, envd APIs require you to first get sandbox connection information through the Sandbox Instances API, then access the sandbox runtime proxy address.
Access Method
Get Connection Information
Call POST /sandboxes/{sandboxID}/connect, make sure the sandbox is running, and get domain and envdAccessToken.
bash
curl -X POST "$SUFY_SANDBOX_API_URL/sandboxes/$SANDBOX_ID/connect" \
-H "X-API-Key: $SUFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeout": 300}'Key response fields:
| Field | Type | Description |
|---|---|---|
domain | string | Sandbox traffic access domain |
envdAccessToken | string | Runtime token used to access envd |
Build the envd Endpoint
envd is exposed through port 49983 by default. When accessed through the sandbox proxy, the endpoint format is:
text
https://49983-{sandboxID}.{domain}Example:
bash
export ENVD_API_BASE="https://49983-$SANDBOX_ID.$SANDBOX_DOMAIN"If domain is empty, the current sandbox connection information is not sufficient for direct access to envd from a browser or external HTTP client. Reconnect the sandbox before accessing envd.
Authentication
envd authenticates requests with the X-Access-Token header:
http
X-Access-Token: <envdAccessToken>Some file download and upload APIs also support signature parameters, but for regular calls, X-Access-Token is recommended.
File download and upload APIs may use signed /files URLs. Process, PTY, and File System Connect RPC APIs use X-Access-Token.
Connect RPC APIs can also use Basic Auth to specify the execution user:
http
Authorization: Basic <base64("user:")>If no user is specified, envd uses the sandbox default user.
Common Headers
| Header | Required | Description |
|---|---|---|
X-Access-Token | Yes | envd runtime access token |
Authorization | No | Basic Auth username used to specify the execution user |
Content-Type | Yes | Use application/json for REST JSON APIs and Connect RPC JSON requests |
Connect-Protocol-Version | Required for Connect RPC requests | Always 1 |
Health Check
Request Path
http
GET /healthReturns 204 No Content when healthy.
Request Example
bash
curl -I "$ENVD_API_BASE/health"Query Runtime Metrics
Request Path
http
GET /metricsResponse Fields
| Field | Type | Description |
|---|---|---|
ts | integer | Current sandbox time, as a Unix timestamp in seconds |
cpu_count | integer | CPU core count |
cpu_used_pct | number | CPU usage percentage |
mem_total | integer | Total memory in bytes |
mem_used | integer | Used memory in bytes |
disk_total | integer | Total disk space in bytes |
disk_used | integer | Used disk space in bytes |
Request Example
bash
curl -X GET "$ENVD_API_BASE/metrics" \
-H "X-Access-Token: $ENVD_ACCESS_TOKEN"Query Environment Variables
Request Path
http
GET /envsReturns an environment variable object. Both keys and values are strings.
Request Example
bash
curl -X GET "$ENVD_API_BASE/envs" \
-H "X-Access-Token: $ENVD_ACCESS_TOKEN"Initialize Runtime
Description
POST /init is used by the system side to initialize or update envd runtime state, such as synchronizing time and metadata, setting the access token, default user, default working directory, environment variables, mounts, and post-init actions.
This is a privileged API. Regular business scenarios usually do not need to call it directly. When creating or restoring a sandbox, the platform performs the required initialization.
Request Path
http
POST /initRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
hyperloopIP | string | No | hyperloop service IP |
envVars | object | No | Environment variables to merge into the runtime |
accessToken | string | No | envd access token. After it is set, it cannot be changed to a different value |
timestamp | string | No | RFC3339 timestamp. Requests older than the most recent initialization are skipped |
defaultUser | string | No | Default execution user |
defaultWorkdir | string | No | Default working directory |
mounts | array | No | File system mounts to configure |
postInitActions | array | No | Commands to run after initialization |
caCertPEM | string | No | CA certificate to inject into the system trust store |
Returns 204 No Content on success.