---
title: How to Send Interactive Stdin to a Sandbox Command (public)
description: Keep a sandbox command&#39;s stdin open and write to it while the command runs over the Harness Runtime API.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/send-exec-stdin/
last_updated: "2026-11-18"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# How to Send Interactive Stdin to a Sandbox Command (public)

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](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) 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](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) with access to the session.
- A running Harness Runtime session with a sandbox. For a sandbox with no harness, see [Run a Sandbox](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/run-sandbox/index.html.md).
- 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:

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

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

```shell
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:

```json
{"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`:

```shell
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](https://docs.digitalocean.com/reference/api/reference/harness-runtime/index.html.md#harness_post_session_sandbox_exec) and [WriteExecStdin](https://docs.digitalocean.com/reference/api/reference/harness-runtime/index.html.md#harness_post_session_sandbox_exec_stdin) in the API reference.