Commands

Commands are the process API for a machine. 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 Machine

with Machine.create(template="base") as machine:
    result = machine.commands.run("echo hello", shell=True)
    print(result.exit_code, result.stdout.strip())

nullspace machine exec mch_... --shell "echo hello"

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

Need	SDK Call	Use When
Run and collect output after exit	`machine.commands.run(...)`	The command is short and bounded.
Stream output while running	`machine.commands.run_streaming(...)` or `run(..., on_stdout=...)`	Logs matter before the process exits.
Start long-running work	`run(..., background=True)`	You need a server or worker process to keep running.
Reconnect to a process	`machine.commands.connect(pid)`	A background process already exists and you need live output.
Manage a process	`list()`, `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 = machine.commands.run("python3", ["-c", "print('hello')"])

nullspace machine exec mch_... python3 -- -c "print('argv')"

{
  "command": "python3",
  "args": ["-c", "print('hello')"],
  "shell": false
}

The raw API body uses command, optional args, and shell.

Working Directory, Environment, And Timeout

result = machine.commands.run(
    "pytest -q",
    shell=True,
    cwd="/workspace/project",
    envs={"PYTHONUNBUFFERED": "1"},
    timeout=120,
)

nullspace machine exec mch_... \
  --cwd /workspace/project --env PYTHONUNBUFFERED=1 --timeout 120 \
  --shell "pytest -q"

cwd must be a valid machine 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.

Get started

Machines

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Commands

Quick Example

Choose An Execution Mode

Shell Strings Vs Argv

Working Directory, Environment, And Timeout

Command Guides

Streaming

Run commands in background

Manage processes

CLI commands

​Quick Example

​Choose An Execution Mode

​Shell Strings Vs Argv

​Working Directory, Environment, And Timeout

​Command Guides

Streaming

Run commands in background

Manage processes

CLI commands

​Related

Quick Example

Choose An Execution Mode

Shell Strings Vs Argv

Working Directory, Environment, And Timeout

Command Guides

Related