Skip to main content
OpenHands is an open-source AI coding agent. Its CLI has a headless mode for scripts and CI. Run it in a Superserve sandbox so its shell commands and file edits stay isolated from your machine.

Via the console

  1. On the Secrets page, create a secret with the Anthropic provider and paste your API key — you only do this once, and the key never enters the sandbox.
  2. Go to console.superserve.ai and click Create sandbox.
  3. Pick the superserve/base template.
  4. Under Advanced Options → Secrets, bind that secret to LLM_API_KEY.
  5. Create the sandbox, open its Terminal, and run:

Via the SDK

The install puts uv and openhands in /usr/local/bin, so every command finds them on PATH. OpenHands reads the model from LLM_MODEL and the key from LLM_API_KEY, but only when you pass --override-with-envs. The value of LLM_API_KEY is a stand-in token — the real key is attached only on requests to Anthropic, never exposed to the agent. OPENHANDS_SUPPRESS_BANNER hides the start-up banner that OpenHands prints on stderr. The last command sets git to send the sandbox’s proxy credentials on the first request. OpenHands clones its public skills repository from GitHub at start-up, and the agent can run git clone too.
In a Superserve sandbox with secrets, images with libcurl 8.13 to 8.17, for example python:3.12 and other Debian 13 images, need git config --global http.proxyAuthMethod basic for git over HTTPS. Without it, git clone hangs. The environment variable GIT_HTTP_PROXY_AUTHMETHOD=basic also works. The superserve/base image doesn’t need this setting.
Open the sandbox in the console, launch the terminal, and run openhands --override-with-envs for the interactive terminal UI.

Run headless

Pass a task with -t and add --headless. OpenHands runs the task in the current directory, prints a summary with the agent’s last message, and exits. Headless mode always approves the agent’s actions, so the agent runs shell commands and edits files without stopping. An agent run can take several minutes. Pass output callbacks to each run() that starts the agent: a streamed run() gets keepalive messages while the agent works, so the connection stays open. A run() without callbacks gets no response until the command ends, and in TypeScript on Node.js it fails after 300 seconds, even with a longer timeoutMs. See Streaming output.
openhands --headless exits with code 0 even when the run fails, for example when the key is not valid. To detect failures, check the exit code, then use JSON output and check for a ConversationErrorEvent, as shown below.

Get JSON output

Add --json to get one JSON event per line on stdout, mixed with a few plain-text status lines. Keep the lines that start with {. Each event has a kind:
  • ActionEvent: a tool call by the agent, with a short summary.
  • ObservationEvent: the result of a tool call.
  • MessageEvent: a message. The last one with source: "agent" holds the final answer, as text blocks in llm_message.content.
  • ConversationErrorEvent: the run failed. code and detail say why.
This run passes only a stderr callback, so the events aren’t printed while they arrive. The callback still keeps the connection open, and stdout holds every event when the run ends. The Conversation ID line at the end of stdout identifies the conversation, so you can continue it later. A nonzero exit code means the command failed, for example when it reached its timeout.

Continue a conversation

OpenHands saves each conversation in ~/.openhands/conversations. Pass the conversation ID to --resume together with a new task to send a follow-up with the earlier context.

Watch long runs

In plain headless mode, OpenHands prints nothing between Agent is working and the final summary. To see progress on a long task, stream the JSON events and print each action’s summary as it arrives. Output can arrive in chunks that split a line, so keep the incomplete last line until the rest arrives. Set the timeout above your longest expected run.
A streamed run stops when the connection drops. For a task that must outlive your process, start OpenHands in the background with its output in a file, and read the file later. See If the connection drops.

Work on a repository

Clone a repository into the sandbox and write the task to a file, so a long task needs no shell quoting. Pass the file to -f, stream OpenHands’ output while it works, then read the diff.

Choose a model

OpenHands calls models through LiteLLM, so LLM_MODEL takes a provider/model ID such as anthropic/claude-sonnet-4-6 or openai/gpt-5.5. To use a model for one run only, pass LLM_MODEL in the command’s env:
To use OpenAI, create a secret with the OpenAI provider, bind it to LLM_API_KEY, and set LLM_MODEL to an openai/... model. For an OpenAI-compatible endpoint on another host, set LLM_BASE_URL to the endpoint, and bind LLM_API_KEY to a custom secret for that host. A provider secret sends the real key only to its provider’s host.

Restrict the network

Auto-approved commands stay inside the sandbox and can’t touch your machine, but the sandbox can still reach the internet. Use network rules to limit where it can connect. Install OpenHands first, because the install needs astral.sh, github.com, and PyPI. With Anthropic, OpenHands then needs only api.anthropic.com to run. If you deny all other traffic, also allow the sandbox’s DNS resolvers, 1.1.1.1/32 and 8.8.8.8/32, so the name resolves.
With these rules, OpenHands still tries to reach github.com and raw.githubusercontent.com at start-up. The sandbox blocks these requests, and the run continues without them. Commands that need other hosts, such as git clone or pip install, fail until you allow those hosts too.

Start from a template

To skip the install in every new sandbox, build a template with OpenHands installed once:
Then create sandboxes with fromTemplate: "openhands" (TypeScript) or from_template="openhands" (Python), and leave out the install command.
If you build from an image with libcurl 8.13 to 8.17, for example python:3.12 or another Debian 13 image, add the step { env: { key: "GIT_HTTP_PROXY_AUTHMETHOD", value: "basic" } } (TypeScript) or EnvStep(env=EnvStepValue(key="GIT_HTTP_PROXY_AUTHMETHOD", value="basic")) (Python). Without it, git clone over HTTPS hangs in sandboxes with secrets. The ubuntu:24.04 image doesn’t need it.

Persist sessions

Pause the sandbox to keep its files, the conversations in ~/.openhands, and its memory. Resume it to continue.

Delete when finished

A paused sandbox is kept until you delete it. When you no longer need the sandbox, delete it. This also deletes its files and saved state.
To delete it from another process, pass its ID to Sandbox.killById() (TypeScript) or Sandbox.kill_by_id() (Python). To delete paused sandboxes automatically, see Auto-delete.