Skip to main content
Execute command in isolated container. Spawns microVM (~2-5s startup).

​
Parameters

ParameterTypeDefaultDescription
commandstringrequiredShell command to execute
imagestringrequiredImage UUID or tag:name
shellbooleantrueWhether command is a shell expression
disposablebooleantrueDiscard changes after execution
directory_state_idinteger-Files from rsync
filesobject-Map of container paths to upload UUIDs: {"/path/in/container": "uuid"} — key is destination, value is UUID
waitbooleantrueBlock until complete
timeoutinteger30Max seconds
envobject-Environment variables
cwdstring/rootWorking directory
stdinstring-Input via stdin
truncate_output_atinteger8000Max bytes for output

​
Examples

Basic: 
{"command": "python --version", "image": "tag:python:3.11"}
With local files: 
{"command": "python /app/main.py", "image": "uuid", "directory_state_id": 42}
Save changes: 
{"command": "pip install flask", "image": "uuid", "disposable": false}
Returns: {"result_image": "new-uuid", "filesystem_changed": true} Async: 
{"command": "python long_task.py", "image": "uuid", "wait": false}
Returns: {"operation_id": "op-xxx"} With uploaded files: 
// Step 1: Upload file
{"tool": "upload", "args": {"content": "print('hello')"}}
// Returns: {"uuid": "file-uuid-123"}

// Step 2: Inject into container and run
{"tool": "run", "args": {
  "command": "python /app/script.py",
  "image": "tag:python:3.11",
  "files": {"/app/script.py": "file-uuid-123"}
}}
Common mistake: The files key is the container path (destination), the value is the UUID (from upload). Not the other way around. One UUID can be mounted to multiple paths.
Environment variables: 
{"command": "echo $MY_VAR", "image": "uuid", "env": {"MY_VAR": "hello"}}

​
Response

{
  "exit_code": 0,
  "timed_out": false,
  "state": "SUCCESS",
  "result_image": "uuid-if-disposable-false",
  "filesystem_changed": true,
  "stdout": "output",
  "stderr": null
}

​
Errors

  • Image not found: Use list_images to find valid UUIDs
  • Directory state not found: Re-run rsync
  • timed_out: true: Increase timeout parameter