Sandbox lifecycle
Create, attach to, and tear down sandboxes.Archive Sandbox
Delete conversations to release their Persistent Volume Claims (PVCs) and free storage resources.
Clone and Attach
Clone a repository and run its setup script in a sandbox, then attach a conversation to the prepared environment.
Start Sandbox
Start a sandbox without a conversation and run commands via the agent-server REST API.
Conversation monitoring & reacting
Observe conversations and react to their state.Conversation Metrics
Retrieve cost and token usage metrics for conversations via CLI tool.
Conversation Tags
Attach key-value metadata to a conversation with tags and read it back from AppConversation.tags.
Finish Callback
Notify an external URL when a conversation finishes using a Stop hook.
React to State WebSocket
React to conversation execution_status changes over WebSocket instead of polling.
Server Info Idle
Poll the idle_time endpoint to detect when a workspace has gone quiet.
Watch Terminal State
Detect confirmed terminal execution_status over WebSocket with proper event handling.
Secrets & authentication
Inject credentials and manage identity.GPG Commit Signing
Configure GPG commit signing on every conversation with a SessionStart hook that imports a key from a custom secret.
Per-Conversation Secrets
Inject per-conversation secrets via REST API as bash env vars and to template an MCP server config bundled in a plugin.
Service Account GitHub PAT
Use one OpenHands account as a service account, overriding the managed GITHUB_TOKEN with each user’s PAT per conversation.
Plugins, skills & MCP
Extend conversations with plugins, skills, and MCP servers.Launch Plugin Badge
Build a no-code /launch link, HTML button, or README badge that loads a plugin.
Load Plugin
Start a conversation with a plugin pre-loaded via the REST API.
Test MCP Config
Validate MCP server configs against a sandbox agent-server via POST /api/mcp/test.
Upload Skills
Upload a local agent-skills directory into a sandbox, then start a conversation that uses them.
Custom agents & tools
Configure the agent and add custom tools.Custom Agent No Browser
Configure agent tools via the agent-server API to exclude the browser tool.
Custom Pip Tool Agent
Load a custom tool from a published pip package via pip install —target and tool_module_qualnames.
Custom Agent With Tool
Add custom server-side tools via source file upload and tool_module_qualnames.
Custom System Prompt
Override the default OpenHands system prompt with a custom one for specialized agents.
Disabled Skills
Persist an account-level deny-list of skills so every conversation starts with them disabled.
Guardrails
Constrain what the agent can do with hooks.Command Blacklist
Block known-dangerous shell commands with a PreToolUse hook bundled in a plugin. Everything not on the blocklist runs normally.
Command Whitelist
Allow only approved shell commands with PreToolUse hooks (whitelist approach for strict security).
Workspace Isolation
Enforce directory boundaries with hooks to prevent agents from navigating or writing outside assigned workspace.