> ## 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

> Configure global or repo-scoped A2A server definitions for Handler.

# 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

```toml theme={null}
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:

```bash theme={null}
handler server add demo --url http://localhost:8000
```

Use repo-scoped config when the server definition belongs with the repo:

```bash theme={null}
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:

```bash theme={null}
handler server list
```

Show one server's resolved configuration:

```bash theme={null}
handler server show demo
```

Validate configured servers and auth references:

```bash theme={null}
handler server validate
```

## Example with auth

```toml theme={null}
version = 1

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

[servers.demo.auth]
type = "bearer"
env = "HANDLER_DEMO_TOKEN"
```

See [Authentication](./authentication) for full auth examples.