Skip to main content
Use machine.commands for foreground and background execution inside a running machine. Use shell=True for authored shell snippets. Use args=[...] for exact argv; shell=True cannot be combined with args.

Foreground commands

CommandResult includes exit_code, stdout, stderr, and optional pid. Non-zero command exits are returned in exit_code; they are not raised as SDK exceptions.

Background processes

The returned BackgroundCommand exposes pid, wait(), kill(), get_logs(), disconnect(), and iteration over new stdout/stderr chunks. Pass callbacks with background=True when you want live output while the process keeps running:

Streaming

You can also pass on_stdout or on_stderr directly to machine.commands.run(...) to use the streaming path. Reconnect to an existing running PID:

Stdin and argv

Command cwd values must be valid machine paths and cannot target runtime-managed paths under /workspace/.nullspace. Process APIs return ProcessInfo(pid, command, running) and CommandLogs(stdout, stderr, output, exit_code).

Async

AsyncMachine exposes the same commands namespace with awaitable methods:

Git helpers

machine.git includes first-class helpers for common repository workflows:
Helpers include clone(), pull(), checkout(), create_branch(), delete_branch(), branches(), add(), commit(), push(), status(), diff(), remote_add(), set_config(), get_config(), configure_user(), add_ssh_key(), and dangerously_authenticate(). commit() uses the repo’s configured Git identity unless you pass author_name and author_email for a one-off commit. Concept: Exec. API reference: execCommand, listProcesses, sendStdin, getProcessLogs, and killProcess.