# Server maintainer guide

This guide is for the person who owns a self-hosted Claude Trigger Router server.

If you are choosing between local use, server maintenance and remote service use, start with `docs/configuration-roles.md`.

## 1. Prepare the server profile

```bash
ctr deploy init --target server
```

Fresh machines can also run `ctr setup` and choose `部署为远程服务端`; setup writes the same server profile shape and intentionally does not start the service.

The command creates a server-oriented config with:

- `HOST: "0.0.0.0"`
- `Runtime.mode: "server"`
- `Runtime.security` defaults for public auth, admin-only bootstrap key, HTTPS/private-network exposure and recommended managed key scopes
- a bootstrap `APIKEY`
- logging enabled
- editable `Models` and `Router.default`

Edit `Models[].key`, `Models[].api`, `Models[].interface` and `Models[].model` before exposing the service.

`GET /api/service-info` returns the same security policy and a deployment checklist so maintainers can verify the live service before sharing the URL.

Remote clients read `GET /api/remote-status` from their local thin proxy. That response now includes discovery and availability summaries so clients can see the remote service role, service-scope boundary, remote model count, upstream service count and next steps without receiving secrets. Keep `/api/registration` redacted and treat it as an observability source, not remote config writeback.

## 2. Diagnose and start

```bash
ctr doctor
ctr start --daemon
ctr status
```

`ctr status` and `ctr doctor` should show:

- current role: `server (router_service)`
- listener: `0.0.0.0:<port>` or the host you configured
- auth state: bootstrap and active managed key counts
- remote client connection hint: `ANTHROPIC_BASE_URL=http://<server-host>:<port>`

## 3. Issue client keys

Keep the bootstrap `APIKEY` for service owners. Use it only to open `/ui`, save config, and manage auth.

Create a managed key for remote users:

```text
POST /api/auth/keys
```

Recommended remote-user scopes:

```json
["client", "read-only"]
```

`client` allows model calls. `read-only` allows ready/status checks such as `/api/health`, `/api/service-info`, compiled model summaries and governance GET endpoints. `operator` is for day-to-day maintenance writes such as restart, governance snapshots, schedules, anomaly thresholds and archive deletion; it cannot read or save config and cannot manage auth keys. Generated secrets are returned once.

## 4. Rotate keys

Use admin auth to rotate a managed key when a remote client changes owner, a secret may have leaked, or a regular maintenance window requires renewal:

```text
POST /api/auth/keys/:id/rotate
```

Rotation creates one replacement key, returns the new secret once, preserves the old key's scopes/quota unless overrides are provided, and immediately revokes the old key. After the client confirms the new secret works, check `GET /api/auth/keys` and `GET /api/auth/audit` for the expected active/revoked state.

Use `POST /api/auth/keys/:id/revoke` when no replacement should be issued.

## 5. Expose safely

Prefer one of these deployment envelopes:

- `config/deploy/docker-compose.server.yaml`
- `config/deploy/systemd/claude-trigger-router.service`

Before exposing the service to other machines:

- keep auth enabled with bootstrap or active managed keys
- put public deployments behind HTTPS reverse proxy or private network access
- give remote users managed `client + read-only` keys, not admin/bootstrap keys
- rotate managed keys during ownership changes or suspected leaks

## 6. Daily maintenance

Use:

```bash
ctr status
ctr doctor
ctr ui
```

`ctr ui` opens the workbench. The maintainer area shows security status, auth scope guidance, quota usage, governance health and routing outcome summaries.

When auth is enabled, `/ui` requires an admin key. A normal browser navigation cannot attach `Authorization: Bearer <admin-key>` by itself, so expose the UI through a private network, local tunnel or HTTPS reverse proxy that injects the admin header after its own authentication. Do not put an admin key in the URL. For a quick API smoke, use:

```bash
curl -H "Authorization: Bearer $CTR_ADMIN_KEY" http://127.0.0.1:5678/api/service-info
```

For model pools, use `GET /api/models/pool-health` for current health and `POST /api/models/pool-health/probe` for an operator-triggered lightweight reachability probe. The probe does not send a model request; it uses `HEAD` against enabled endpoints, records latency for reachable endpoints, and records failures into the existing cooldown/circuit breaker state.

This server profile still does not provide node/cluster orchestration or a hosted cloud control plane. If remote clients report missing expected models in availability, inspect `Registration.models`, `Registration.upstream_services` and model pool health on this server.