Runtime API

Runtime APIs are served from the sandbox envdUrl returned by create, detail, or connect. They operate inside that sandbox runtime.

Authentication

X-Access-Token: <envdAccessToken>

Health endpoints are public:

GET {envdUrl}/health
GET {envdUrl}/
OPTIONS *

Run Command

POST {envdUrl}/run

curl -sS "$ENVD_URL/run" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "cmd": "python --version",
    "cwd": "/root",
    "timeoutMs": 30000
  }'

Use SDK or CLI helpers for streaming and background process management. The CLI maps this flow to:

seacloud sandbox exec <sandbox_id> "python --version"
seacloud sandbox exec --background <sandbox_id> "python server.py"

File Helpers

Method	Path	Purpose
GET	{envdUrl}/files?path=/root	List files.
GET	{envdUrl}/file?path=/root/app.py	Read a file.
POST	{envdUrl}/file	Write a file.
POST	{envdUrl}/files	Upload or write files.
POST	{envdUrl}/files/batch	Batch file operations.
POST	{envdUrl}/files/compose	Compose files from multiple parts.

Example write:

curl -sS -X POST "$ENVD_URL/file" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "path": "/root/workspace/hello.txt",
    "content": "hello sandbox"
  }'

RPC Groups

Advanced SDK calls use runtime RPC groups:

Group	Route prefix
Filesystem	POST {envdUrl}/filesystem.Filesystem/*
Process	POST {envdUrl}/process.Process/*

Prefer SDKs for these routes unless you are debugging a low-level integration.

Runtime Metrics

GET {envdUrl}/metrics

Returns a runtime snapshot from inside the sandbox. For dashboard metrics, use GET /sandboxes/:sandboxID/metrics.