Skip to main content

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

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

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. You can point it at another compatible documentation MCP endpoint when testing docs locally: 
export HANDLER_DOCS_MCP_URL=http://localhost:3000/mcp
handler server run agent
For fully offline runs, disable the docs toolset: 
export HANDLER_DOCS_MCP_ENABLED=false
handler server run agent

​
Choose a model

The built-in agent uses Google ADK with LiteLLM against an Ollama-compatible endpoint. You can override the model directly: 
handler server run agent --model gemma4:e4b
Or set environment variables: 
export OLLAMA_MODEL=gemma4:e2b
export OLLAMA_API_BASE=http://localhost:11434
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

handler server run agent --auth
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

handler server run push
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.