Run
Run a command in a VM, and poll its result.
The Run object
run_id
String
The run's id.
state
"running" | "completed" | "failed"
Lifecycle state.
stdout, stderr
String
The program's own output, once available.
stdout_encoding, stderr_encoding
"utf-8" | "base64"
How
stdout/stderr are encoded. Output that isn't valid UTF-8 is sent base64-encoded and tagged here.exit_code
Int
The command's exit code, once completed.
fail_reason
String
Set when
state is failed: a platform-side explanation, distinct from stderr (the program's own error output).POST/v1/vms/{id}/runs
Request
command
String
Required
The command to run.
session_id
String
Run inside an existing session (shared shell state). Defaults to the VM's default session.
timeout
Int
Execution/kill bound in seconds: the longest the command may run before it's killed. Defaults to
300.time_to_background
Int
Sync window in seconds: how long the HTTP call blocks before returning a pollable
run_id instead of waiting for completion. 0 returns immediately after the command starts. Defaults to 300. Does not bound how long the command itself runs; that's timeout.env
Object
Environment-variable overrides for this run.
cwd
String
Working directory for this run. Defaults to
/.Response
A synchronous run (one that completes inside the sync window) returns the completed shape directly:
run_id
String
The recorded run's id.
state
String
completed for this response shape.stdout, stderr
String
The program's own output.
stdout_encoding, stderr_encoding
"utf-8" | "base64"
See the Run object.
exit_code
Int
The command's exit code.
A run that outlives the sync window returns the in-progress shape instead:
run_id
String
The id to poll with GET /v1/vms/{id}/runs/{run_id}.
state
String
running for this response shape.Example
bash
curl -X POST localhost:7240/v1/vms/$VM/runs \
-H "Content-Type: application/json" \
-d '{"command":"echo hello from fork"}'GET/v1/vms/{id}/runs/{run_id}
Fetch one run, including its output once it's available.
Response
Returns a Run object.
Example
bash
curl localhost:7240/v1/vms/$VM/runs/$RUN_ID