Skip to main content
sandbox.commands runs commands inside a live sandbox. AsyncSandbox.commands provides the async equivalent.

​
Command Execution

MethodUse
run(command, args=None, shell=False, cwd=None, envs=None, timeout=None, background=False, on_stdout=None, on_stderr=None)Run a command, optionally stream output, or start it in the background.
stream(...)Stream command output from a long-running foreground execution.
result = sandbox.commands.run(
    "python3 -m pytest",
    shell=True,
    cwd="/workspace/repo",
    envs={"PYTHONUNBUFFERED": "1"},
    timeout=300,
)
print(result.exit_code, result.stdout)
Use shell=True for authored shell strings. Use args=[...] when exact argument boundaries matter.

​
Background Processes

MethodUse
run(..., background=True)Start a long-running command and return a process handle.
list()List running commands and PTY sessions.
send_stdin(pid, data)Send input to a process.
logs(pid)Fetch stdout, stderr, and interleaved output.
kill(pid)Stop a process by PID.
server = sandbox.commands.run(
    "python3 -m http.server 8080",
    shell=True,
    cwd="/workspace",
    background=True,
)
try:
    print(sandbox.get_url(8080))
    input("Open the URL, then press Enter to stop the server...")
finally:
    server.kill()