Skip to main content
Commands are the process API for a sandbox. Use them to run one-off checks, install packages, start services, stream logs, send stdin, inspect processes, and stop background work.

​
Quick Example

from nullspace import Sandbox

with Sandbox.create(template="base") as sandbox:
    result = sandbox.commands.run("echo hello", shell=True)
    print(result.exit_code, result.stdout.strip())
CommandResult includes exit_code, stdout, stderr, and, when returned by the API, pid. A command that exits non-zero still returns a result; check exit_code before treating the work as successful.

​
Choose An Execution Mode

NeedSDK CallUse When
Run and collect output after exitsandbox.commands.run(...)The command is short and bounded.
Stream output while runningsandbox.commands.run_streaming(...) or run(..., on_stdout=...)Logs matter before the process exits.
Start long-running workrun(..., background=True)You need a server or worker process to keep running.
Reconnect to a processsandbox.commands.connect(pid)A background process already exists and you need live output.
Manage a processlist(), get_logs(), send_stdin(), kill()You need process inventory or cleanup.

​
Shell Strings Vs Argv

Use shell=True for authored shell snippets, pipelines, redirects, and environment expansion. Use args when you want exact argument boundaries without shell parsing. The API rejects requests that combine shell=True with non-empty args. 
result = sandbox.commands.run("python3", ["-c", "print('hello')"])
The raw API body uses command, optional args, and shell.

​
Working Directory, Environment, And Timeout

result = sandbox.commands.run(
    "pytest -q",
    shell=True,
    cwd="/workspace/project",
    envs={"PYTHONUNBUFFERED": "1"},
    timeout=120,
)
cwd must be a valid sandbox path and cannot target Nullspace runtime-managed paths under /workspace/.nullspace. envs are added only for that execution; they do not persist after the command exits unless your command writes them to disk.

​
Command Guides

Streaming

Stream stdout and stderr while a command is still running.

Run commands in background

Start long-running processes and manage them by PID.

Manage processes

List processes, fetch logs, send stdin, and terminate work.

CLI commands

Execute commands and stream processes from the Nullspace CLI.