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.

​
Servers

Handler can load named server definitions from two places:
  • global config at $XDG_CONFIG_HOME/handler/servers.toml
  • repository-local config at .handler/servers.toml
Handler also includes a built-in global entry named Handler Agent at http://localhost:8000. It appears in the TUI server picker even before you create a servers.toml file, so new users can connect to Handler’s bundled embedded agent immediately. If you define your own server with the same name or URL, Handler uses your entry instead of adding the built-in one. Repository-local config is useful when a project should travel with a shared agent URL or auth shape, while secrets continue to come from environment variables on each developer machine.

​
File format

version = 1

[servers.local]
url = "http://localhost:8000"
Each server entry needs a url. Auth is optional.

​
Global vs repository-local

Use global config by default: 
handler server add demo --url http://localhost:8000
Use repository-local config when the server definition belongs with the repo: 
handler server add demo --url http://localhost:8000 --repository

​
Validation helpers

Handler validates server files when it loads them and skips only the invalid entries instead of failing the whole file. These commands help you inspect what is available: 
handler server list
handler server show demo
handler server validate

​
Example with auth

version = 1

[servers.demo]
url = "https://agent.example.com"

[servers.demo.auth]
type = "bearer"
env = "HANDLER_DEMO_TOKEN"
See Authentication for full auth examples.