> ## Documentation Index
> Fetch the complete documentation index at: https://handler.alduncanson.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local servers

> Run Handler's embedded A2A agent and local webhook server for development, demos, and integration testing.

# Run local A2A servers

Handler ships with two useful local servers for development work:

* a documentation-aware embedded A2A agent for local testing and Handler help
* a webhook receiver for task push notifications

## Run the embedded agent

Start Handler's bundled local A2A agent:

```bash theme={null}
handler server run agent
```

By default it binds to `0.0.0.0:8000`.

In the TUI, Handler includes this local agent as the built-in `Handler Agent`
server. Selecting it and pressing **CONNECT** auto-starts the embedded agent if
nothing is already listening at `http://localhost:8000`.

The embedded agent is Handler-aware: it uses Google ADK tools to connect to
Handler's hosted documentation MCP server at
`https://handler.alduncanson.com/mcp`. That lets it answer questions about the
Handler CLI, TUI, MCP bridge, authentication, local servers, and common A2A
workflows from the current docs instead of only relying on model memory.

## Choose a model

The built-in agent uses Google ADK with LiteLLM against an Ollama-compatible
endpoint.

You can override the model directly:

```bash theme={null}
handler server run agent --model gemma4:e4b
```

Or set environment variables:

```bash theme={null}
export OLLAMA_MODEL=gemma4:e2b
```

```bash theme={null}
export OLLAMA_API_BASE=http://localhost:11434
```

```bash theme={null}
handler server run agent
```

If you do not override it, Handler defaults to `gemma4:e2b` and
`http://localhost:11434`.

## Protect the local agent with an API key

Require API key auth with a generated key:

```bash theme={null}
handler server run agent --auth
```

```bash theme={null}
handler server run agent --auth --api-key my-secret
```

When auth is enabled, Handler protects the A2A request endpoints with an API
key. If you do not provide one explicitly, Handler generates a random key for
you.

The agent card and health endpoints stay readable without auth so clients can
still discover the server.

## Run the push notification receiver

Start the local webhook receiver on the default port:

```bash theme={null}
handler server run push
```

```bash theme={null}
handler server run push --port 9001
```

By default it binds to `127.0.0.1:9000` and exposes these endpoints:

* `POST /webhook` receives task notifications
* `GET /webhook` returns a simple validation response
* `GET /notifications` lists received notifications
* `POST /notifications/clear` clears stored notifications

## End-to-end push notification test

1. Start the webhook receiver with `handler server run push`.
2. Start or connect to an agent.
3. Send a message that creates a long-running task.
4. Point that task at `http://127.0.0.1:9000/webhook` with `handler task notification set`.
5. Inspect received events at `http://127.0.0.1:9000/notifications`.

This is a simple way to verify that an agent's push flow works before wiring it
into a real webhook consumer.