Skip to main content

​
Configure A2A servers

Handler can load configured A2A server definitions from two places:
  • global config at $XDG_CONFIG_HOME/handler/servers.toml
  • repo-scoped 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. Handler does not add the built-in entry when a configured server already uses the Handler Agent name or the http://localhost:8000 URL. When the TUI auto-starts the embedded agent and port 8000 is already occupied, it tries the next available local port. Repo-scoped 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 repo-scoped

Use global config by default: 
handler server add demo --url http://localhost:8000
Use repo-scoped 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. Use these commands to inspect what is available. List every configured server Handler can load: 
handler server list
Show one server’s resolved configuration: 
handler server show demo
Validate configured servers and auth references: 
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.