> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-vertex-agent-server-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Agent Server

> Install and run an OpenHands Agent Server on your machine, then connect to it from the SDK.

export const path_to_script_0 = "examples/02_remote_agent_server/01_convo_with_local_agent_server.py"

Run a local Agent Server when you want a backend process to host OpenHands conversations over HTTP and WebSocket. This is the simplest setup for testing Agent Canvas-style backends, local integrations, and client-server SDK applications.

## Install

Create a Python environment and install the server package and its SDK dependencies:

```bash theme={null}
uv venv
source .venv/bin/activate
uv pip install -U \
  openhands-sdk \
  openhands-tools \
  openhands-workspace \
  openhands-agent-server
```

If you are working from the `OpenHands/software-agent-sdk` repository, see [Agent Server Package § Install](/sdk/arch/agent-server#install) for the `uv`-based setup.

## Start Without Authentication

For local development on your own machine, start the server on loopback:

```bash theme={null}
python -m openhands.agent_server --host 127.0.0.1 --port 8000
```

Verify that it is running:

```bash theme={null}
curl http://127.0.0.1:8000/health
```

Open the API docs at `http://127.0.0.1:8000/docs`.

If `SESSION_API_KEY` (legacy alias) or `OH_SESSION_API_KEYS_*` is already set in your shell, the server will require that key for `/api/*` requests. Unset those variables for unauthenticated local-only testing.

<Warning>
  This unauthenticated mode is only appropriate for local development. Do not bind an unauthenticated server to a public or shared network interface.
</Warning>

## Start With an API Key

Set a session API key before starting the server:

```bash theme={null}
export OH_SESSION_API_KEYS_0="$(openssl rand -hex 32)"
export OH_SECRET_KEY="$(openssl rand -hex 32)"

python -m openhands.agent_server --host 127.0.0.1 --port 8000
```

Requests to `/api/*` must include the session key. This request returns the conversation count when the key is accepted:

```bash theme={null}
curl \
  -H "X-Session-API-Key: $OH_SESSION_API_KEYS_0" \
  http://127.0.0.1:8000/api/conversations/count
```

<Note>
  `OH_SECRET_KEY` encrypts sensitive values stored with conversations, including LLM API keys and secrets. Keep it stable across restarts. If it changes, previously encrypted values cannot be restored.
</Note>

## Connect From the SDK

Use `Workspace(host=..., api_key=...)` to connect SDK code to the server:

```python theme={null}
import os

from pydantic import SecretStr

from openhands.sdk import Conversation, LLM, Workspace
from openhands.tools.preset.default import get_default_agent


llm = LLM(
    model=os.environ.get("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=SecretStr(os.environ["LLM_API_KEY"]),
)
agent = get_default_agent(llm=llm, cli_mode=True)  # disable browser-automation tools

workspace = Workspace(
    host="http://127.0.0.1:8000",
    api_key=os.environ["OH_SESSION_API_KEYS_0"],
    working_dir="workspace/project",
)

conversation = Conversation(agent=agent, workspace=workspace)
conversation.send_message("Create a NOTES.md file with three facts about this project.")
conversation.run()
conversation.close()
```

If the server was started without `OH_SESSION_API_KEYS_0`, remove the `api_key=...` argument.

The `working_dir` value is relative to the server's process working directory. See [Runtime Files](/sdk/arch/agent-server#runtime-files) for the default directory layout.

## Connect From Another Service

For a non-SDK backend service, pass the session API key as `X-Session-API-Key`:

```bash theme={null}
curl \
  -H "X-Session-API-Key: $OH_SESSION_API_KEYS_0" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:8000/api/conversations/count
```

Keep the Agent Server bound to `127.0.0.1` when the backend runs on the same machine. If the backend runs on another host, use a private network or reverse proxy, enable TLS, and restrict network access to trusted callers.

For CORS configuration and running directly from a checkout of `OpenHands/software-agent-sdk`, see the [Agent Server Package](/sdk/arch/agent-server) page.

## Ready-to-Run Example

<Note>
  This example is available on GitHub: [examples/02\_remote\_agent\_server/01\_convo\_with\_local\_agent\_server.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/01_convo_with_local_agent_server.py).
</Note>

The example starts a local Agent Server subprocess, waits for it to become healthy, connects with `Workspace(host=...)`, and runs a `RemoteConversation`.

You can run the example code as-is.

<Note>
  The model name should follow the [LiteLLM convention](https://models.litellm.ai/): `provider/model_name` (e.g., `anthropic/claude-sonnet-4-5-20250929`, `openai/gpt-4o`).
  The `LLM_API_KEY` should be the API key for your chosen provider.
</Note>

<CodeGroup>
  <CodeBlock language="bash" filename="Bring-your-own provider key" icon="terminal" wrap>
    {`export LLM_API_KEY="your-api-key"\nexport LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"  # or openai/gpt-4o, etc.\ncd software-agent-sdk\nuv run python ${path_to_script_0}`}
  </CodeBlock>

  <CodeBlock language="bash" filename="OpenHands Cloud" icon="terminal" wrap>
    {`# https://app.all-hands.dev/settings/api-keys\nexport LLM_API_KEY="your-openhands-api-key"\nexport LLM_MODEL="openhands/claude-sonnet-4-5-20250929"\ncd software-agent-sdk\nuv run python ${path_to_script_0}`}
  </CodeBlock>
</CodeGroup>

<Tip>
  **ChatGPT Plus/Pro subscribers**: You can use `LLM.subscription_login()` to authenticate with your ChatGPT account and access Codex models without consuming API credits. See the [LLM Subscriptions guide](/sdk/guides/llm-subscriptions) for details.
</Tip>

## Troubleshooting

* **401 Unauthorized**: Check that the client sends `X-Session-API-Key` and that it matches `OH_SESSION_API_KEYS_0`.
* **Secrets are missing after restart**: Set a stable `OH_SECRET_KEY` before starting the server.
* **The server is reachable locally but not from another machine**: Use `--host 0.0.0.0` only behind trusted network controls, then check firewall and proxy rules.
* **CORS errors in a browser**: Set `OH_ALLOW_CORS_ORIGINS_0` to the browser app origin.
* **Port conflict**: Start with another port, for example `--port 8001`.

## Next Steps

* [Agent Server Package](/sdk/arch/agent-server) - Installation, security, and operational guidance.
* [Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox) - Run the server in an isolated Docker workspace.
* [API Sandboxed Server](/sdk/guides/agent-server/api-sandbox) - Start hosted runtime workspaces.
* [Agent Server API Reference](/sdk/guides/agent-server/api-reference/server-details/alive) - Browse generated endpoint docs.