Run Commands

Commands are executed inside the sandbox through runtime process APIs. SDK users should not pass X-Access-Token manually; it is derived from create/connect responses.

Run A Foreground Command

Node

const result = await sandbox.commands.run("sh", {
  args: ["-lc", "pwd && ls -la /root/workspace"],
  timeoutMs: 30_000,
});

console.log(result.exitCode, result.stdout, result.stderr);

Python

result = sandbox.commands.run(
    "sh",
    args=["-lc", "pwd && ls -la /root/workspace"],
    timeout_ms=30_000,
)
print(result["exit_code"], result["stdout"], result["stderr"])

Go

commands, _ := sbx.Commands()
result, err := commands.Run(ctx, "sh", &sandbox.CommandRunOptions{
  Args: []string{"-lc", "pwd && ls -la /root/workspace"},
})

Start A Background Service

Use background commands for preview servers, workers, or long-running jobs.

const handle = await sandbox.commands.run("python3", {
  args: ["-m", "http.server", "3000", "--bind", "0.0.0.0", "--directory", "/root/workspace"],
  background: true,
});

console.log("pid", handle.pid);
console.log("open", sandbox.getHost(3000));

Raw /run Contract

The synchronous runtime helper accepts a command payload and returns captured output.

POST {envdUrl}/run
X-Access-Token: <envdAccessToken>
Content-Type: application/json

{
  "cmd": "sh",
  "args": ["-lc", "pwd && echo ok"],
  "cwd": "/root/workspace",
  "env": { "FOO": "bar" },
  "timeoutMs": 30000,
  "stdin": ""
}

{
  "stdout": "/root/workspace\nok\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 42
}

Working Directory And Environment

await sandbox.commands.run("npm", {
  args: ["run", "start", "--", "--host", "0.0.0.0", "--port", "3000"],
  cwd: "/root/workspace/app",
  env: { NODE_ENV: "development" },
  background: true,
});

Field	Unit	Purpose
cwd	path	Directory where the command starts.
env	map	Per-command environment overrides.
timeoutMs	milliseconds	Runtime command budget.
background	boolean	Return a handle while the process keeps running.

Streaming And Process RPC

The runtime process API includes start, connect, stdin, signal, list, and result flows. Use these lower-level process routes when you need streaming output, interactive stdin, or explicit signal handling.

POST /process.Process/Start
X-Access-Token: <envdAccessToken>
Connect-Protocol-Version: 1
Content-Type: application/connect+json

{
  "process": {
    "cmd": "bash",
    "args": ["-lc", "ls -la"],
    "cwd": "/root/workspace"
  },
  "tag": "inspect",
  "stdin": false
}

/process.Process/Start, /process.Process/Connect, and /filesystem.Filesystem/WatchDir are Connect server-streaming routes and should use Content-Type: application/connect+json. Non-streaming RPC routes use Content-Type: application/json.

Timeout distinction

Sandbox lifecycle timeout is seconds. Command timeoutMs is milliseconds. Keep both explicit in code reviews.

Common Failures

Symptom	Cause
Command times out	Runtime command timeout is too short; increase timeoutMs.
Server exits immediately	Start command failed or dependency install did not finish.
Public URL returns 502	Server is not listening on the requested port or binds only to 127.0.0.1.
sh not found	Template image does not contain /bin/sh; use a compatible template or command.