Process I/O

commands.run() returns everything at once when the command ends, which is all a quick command needs. Commands that run longer are worth bounding, watching, or feeding input to while they run. These options cover that; they layer onto the same run() call and none of them change its return value.

Timeouts

Both commands.run() and code.run() accept a timeout parameter, in seconds. When the timeout is reached, the guest work is interrupted and the call returns instead of waiting for it to finish.

with Sandbox.create() as sandbox:
    result = sandbox.code.run("import time; time.sleep(30)", timeout=3)

A shell command that hits its timeout returns with exit_code 124:

result = sandbox.commands.run("sleep 30", timeout=3)
print(result.exit_code)  # 124

Interrupting a command

A command no longer has to run to its timeout. interrupt() stops whatever is in the foreground, and the call that was waiting returns with exit code 130:

import threading

with Sandbox.create() as sandbox:
    threading.Timer(1.0, sandbox.commands.interrupt).start()

    result = sandbox.commands.run("sleep 300")
    print(result.exit_code)  # 130

The command really stops. This is not the caller walking away while the guest keeps working, so the sandbox is yours again immediately. Ctrl-C works too. It used to do nothing while a command was running, because KeyboardInterrupt could not land on a thread blocked inside the emulator. It now reaches the command, which makes an interactive REPL behave the way you would expect.

code.run() cannot be interrupted yet, so use timeout there.There is no signal parameter, and none is needed: run() blocks, so Ctrl-C reaches it directly and timeout already covers deadlines. The TypeScript SDK needs an AbortSignal because its call returns a promise and the caller keeps going.A command that ignores the interrupt runs to its own deadline and is recovered the same way a timeout is.

Streaming output

commands.run() hands back everything at once, when the command ends. For a build or a test run that is a long wait followed by a wall of text, so it also takes on_stdout and on_stderr, called with each piece of output as it arrives:

import sys

with Sandbox.create() as sandbox:
    result = sandbox.commands.run(
        "for i in 1 2 3; do echo step $i; sleep 1; done",
        timeout=60,
        on_stdout=sys.stdout.write,
    )

    print(result.exit_code)  # 0

The return value does not change, so you can add a callback to existing code and nothing else moves. Chunks are verbatim, exactly the bytes the program wrote, while result.stdout trims its trailing newline: joining the chunks gives you "hi\n" where stdout gives you "hi". Chunks arrive as the guest produces output, not on a fixed schedule. A command printing two hundred lines with no pauses delivers them in one chunk; one printing a line a second delivers a chunk per line. A command that finishes quickly delivers a single chunk, which is indistinguishable from not streaming, and that is correct: there was nothing to stream. Streaming composes with interrupts. The chunks that arrived before the stop are kept, and the result still carries exit code 130.

on_stdout and on_stderr are ordered against each other only when the writes are separated in time. Two processes that both flush as they exit can arrive stdout-first even though stderr was written first, because the two streams travel separately. Use one callback if you need a single ordered transcript.

code.run() does not stream, and does not accept on_stdout. Shell commands are what tend to run long enough to be worth watching.

Sending input

stdin gives the command something to read. A str or bytes becomes that command’s entire input, ending with a real EOF:

result = sandbox.commands.run("sort", stdin="banana\napple\ncherry\n")
print(result.stdout)  # apple\nbanana\ncherry

Input is byte-exact, so binary works the same way:

result = sandbox.commands.run("sha256sum", stdin=open("logo.png", "rb").read())

Without stdin a command’s input is closed, which is why cat with no stdin returns at once rather than hanging.

Streaming input

Pass a queue.Queue when what you send next depends on what came back. That puts the command on a terminal, so you write as it runs and putting None ends its input. run() blocks, so put from on_stdout or from another thread:

import queue

inbox = queue.Queue()
seen = []
step = 0

def on_stdout(chunk):
    global step
    seen.append(chunk)
    text = "".join(seen)
    if step == 0 and ">>>" in text:
        step = 1
        inbox.put("print(40 + 2)\n")
    elif step == 1 and "42" in text:
        step = 2
        inbox.put(None)

result = sandbox.commands.run("python3 2>&1", stdin=inbox, on_stdout=on_stdout, timeout=60)

Match on the output so far rather than the chunk you were handed, and step through once: the prompt comes back after every answer. stdin accepts a str, bytes, a queue.Queue, or any iterable. An iterable is read one chunk at a time as the command runs, and running out ends the input:

def lines():
    yield "alpha\n"
    yield "beta\n"

result = sandbox.commands.run("head -2", stdin=lines(), timeout=60)

Use tty=True for a terminal with no input of its own, and timeout=0 for no deadline, which is what an interactive session wants. Ctrl-C works throughout, and interrupts the command in the guest.

Close the stream only once the command has read what you sent it, by putting your input in response to output as above. Closing early is ignored and the command keeps waiting. If you have all the input up front, pass a string instead.

Get Started

TypeScript SDK

Python SDK

Embedded preview (In Iframe)

CLI

Resources

Process I/O

Timeouts

Interrupting a command

Streaming output

Sending input

Streaming input

​Timeouts

​Interrupting a command

​Streaming output

​Sending input

​Streaming input

Timeouts

Interrupting a command

Streaming output

Sending input

Streaming input