Via the console
- 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.
- Go to console.superserve.ai and click Create sandbox.
-
Pick the
superserve/basetemplate. -
Under Advanced Options → Secrets, bind that secret to
LLM_API_KEY. -
Create the sandbox, open its Terminal, and run:
Via the SDK
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.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.
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 shortsummary.ObservationEvent: the result of a tool call.MessageEvent: a message. The last one withsource: "agent"holds the final answer, astextblocks inllm_message.content.ConversationErrorEvent: the run failed.codeanddetailsay why.
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 betweenAgent 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.
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, soLLM_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:
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 needsastral.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.
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: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.Sandbox.killById() (TypeScript) or Sandbox.kill_by_id() (Python). To delete paused sandboxes automatically, see Auto-delete.