Skip to main content
Use nullspace sandbox exec for one-off commands and nullspace sandbox process ... for background process management.

​
Foreground Commands

Run a shell command: 
nullspace sandbox exec sb_123 --shell "echo hello && python3 --version"
Run a structured command with arguments: 
nullspace sandbox exec sb_123 python3 -- -c "print('hello')"
Use --cwd, --env, and --timeout to control execution: 
nullspace sandbox exec sb_123 \
  --cwd /workspace \
  --env PYTHONUNBUFFERED=1 \
  --timeout 120 \
  --shell "pytest -q"
Do not combine --shell with structured argv for the same command. Shell mode treats the command as an authored shell string; argv mode preserves argument boundaries.

​
Streaming Output

Use the process stream command when you want stdout and stderr as the command runs: 
nullspace sandbox process stream sb_123 python3 -- -u script.py
process stream also accepts --timeout, --cwd, repeatable --env, --shell, and --json: 
nullspace sandbox process stream sb_123 \
  --cwd /workspace \
  --env PYTHONUNBUFFERED=1 \
  --timeout 120 \
  --shell "python3 -u script.py"
Streaming uses the sandbox exec WebSocket channel underneath. With --json, the command suppresses live printing and emits final exit_code, stdout, stderr, and pid.

​
Background Processes

Start long-running work in the background: 
nullspace sandbox exec sb_123 \
  --shell "python3 -m http.server 8080" \
  --background
Then list, inspect logs, attach, send stdin, or kill by PID: 
nullspace sandbox process list sb_123
nullspace sandbox process logs sb_123 1234
nullspace sandbox process attach sb_123 1234
printf "q" | nullspace sandbox process stdin sb_123 1234
nullspace sandbox process kill sb_123 1234
Add --json to process list, logs, stdin, kill, stream, or attach when another program needs structured output. stdin --json reports bytes_sent; attach --json reports the final command result.

​
Code Interpreter

For notebook-style stateful code, use the code interpreter commands instead of plain shell exec: 
nullspace sandbox code run sb_123 "x = 41; x + 1" --json
nullspace sandbox code install sb_123 numpy pandas
nullspace sandbox code context create sb_123 --cwd /workspace
sandbox code run-job list is available for read-only hosted beta inspection. sandbox code run-job create, get, cancel, and wait are not part of the hosted private beta launch surface because remote host-agent routing for queued code runs is not implemented yet. For short one-off language snippets that should use command execution rather than notebook state, the process namespace also exposes: 
nullspace sandbox process code-run sb_123 "print('hello')" --language python --json

​
Exit Codes And JSON

Use --json on supported commands when an agent or script needs structured results: 
nullspace sandbox exec sb_123 --shell "python3 -m pytest -q" --json
If a CLI command fails, the process exits non-zero. See Error Codes for stable error-code anchors.