> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vpod.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Process I/O

> Bound, interrupt, stream, and feed input to commands while they run.

`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()`](/sdk/python/sandbox) 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.

```python theme={null}
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`:

```python theme={null}
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`:

```python theme={null}
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.

<Note>
  `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.
</Note>

## 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:

```python theme={null}
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. What the callbacks receive concatenates to exactly the `stdout` you get without them, so you can add one to existing code and nothing else moves.

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`.

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

## Sending input

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

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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.

<Warning>
  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.
</Warning>