How to Send Interactive Stdin to a Sandbox Commandpublic

Last verified 18 Nov 2026

DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. See What You Can Build for example use cases.

You can leave a command’s stdin open in a DigitalOcean Harness Runtime sandbox and write to it while the command runs. Use this to drive a REPL, answer a prompt, or feed a long-running process. Output on stdout and stderr still streams over Server-Sent Events (SSE). Writes to stdin are separate short HTTP requests keyed by an exec_id.

By default, POST /v2/harness-runtime/sessions/{session_id}/sandbox/exec sends an optional one-shot stdin payload and then closes stdin. Interactive stdin uses two calls instead: start the command with keep_stdin_open: true on an event stream, then write chunks to /sandbox/exec/{exec_id}/stdin.

Note

Interactive stdin is enabled per team. If it is not enabled for your team, a request with keep_stdin_open returns 403.

Prerequisites

  • A DigitalOcean API token with access to the session.
  • A running Harness Runtime session with a sandbox. For a sandbox with no harness, see Run a Sandbox.
  • A session created from a template image that supports interactive stdin. Older sessions return 409 until you create a new session from an updated template.

Start a Command With Stdin Open

Start the command with Accept: text/event-stream (or the stream=1 query parameter) and set keep_stdin_open to true. You can include an optional first stdin chunk as base64 in the same body. Replace <session-id> with the session UUID and $DIGITALOCEAN_TOKEN with your token:

curl -N -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"argv":["python3","-i"],"keep_stdin_open":true}' \
  "https://api.digitalocean.com/v2/harness-runtime/sessions/<session-id>/sandbox/exec"

keep_stdin_open without an event stream returns 400, because a buffered response returns only at exit and would never give you the exec_id.

When the guest has registered the exec, the stream begins with a started event that carries the exec_id. Later events are stdout, stderr, and exit, the same as streaming exec without interactive stdin. The started event is sent only when keep_stdin_open is true.

event: started
data: {"exec_id":"<exec-id>"}

event: stdout
data: {"data":"<base64>"}

event: exit
data: {"exit_code":0,"duration_ms":41234}

Leave this stream open while you write stdin. Closing or canceling the stream ends the command.

Write Stdin to the Running Command

Each write is a short POST to the stdin route. offset is required and is the count of stdin bytes the guest has already accepted. data is base64. Set eof to true to close stdin after the write. A write needs data, eof, or both. Each decoded write is at most 1 MiB.

Start at offset 0 for the first write after any optional first chunk in the start request. If the start request sent N decoded stdin bytes, the first stdin POST uses offset equal to N.

curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"cHJpbnQoImhlbGxvIikK","offset":0,"eof":false}' \
  "https://api.digitalocean.com/v2/harness-runtime/sessions/<session-id>/sandbox/exec/<exec-id>/stdin"

A successful write returns the new accepted byte count:

{"offset":15}

Use that value as offset on the next write. When the process should see end-of-file, send a final write with eof set to true:

curl -X POST \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"offset":15,"eof":true}' \
  "https://api.digitalocean.com/v2/harness-runtime/sessions/<session-id>/sandbox/exec/<exec-id>/stdin"

Follow Offset Rules for One Writer

The stdin stream is one byte pipe. Treat writes as one logical sequence. The guest compares your offset to the bytes it has already accepted:

Client offset Result
Equal to bytes accepted Appends the chunk and returns the new total.
Lower than bytes accepted Treats the write as a retry, trims the overlap, and appends the rest so a lost response does not duplicate bytes.
Higher than bytes accepted Returns 409. Bytes are missing. A second writer that does not know the current offset is refused the same way.
Omitted Returns 400.

eof: true succeeds once. A later write or a second eof returns 409. Several clients may read the output SSE stream. That does not extend to stdin writers.

Handle Errors and Limits

Common responses for stdin writes:

Status When
200 with {"offset":...} The write was accepted.
400 Missing offset, body over 1 MiB, bad base64, or neither data nor eof.
403 You have no access grant on the session, or interactive stdin is not enabled for your team.
404 Unknown session, or an unknown or finished exec_id.
409 The stdin stream is already closed, an offset gap, or the session’s template image does not support interactive stdin.

Streaming exec with keep_stdin_open uses the streaming timeout: omitted timeout_seconds defaults to 900 seconds and caps at 900 seconds. Writes to stdin do not extend that budget. The HTTP route for the event stream may end after about 16 minutes even while stdin writes keep arriving.

For field-level detail, see ExecInSandbox and WriteExecStdin in the API reference.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.