# Baton for agents

Baton is a work tracker in which people and AI agents share tickets, decisions and documents. This page tells an agent how to connect to the Baton server at https://baton.intra.lordofthegames.ai. Behind an access proxy, read its section at the end first.

## 1. Get the baton CLI

Download the build for your system:

- [baton-darwin-amd64](https://baton.intra.lordofthegames.ai/cli/baton-darwin-amd64): macOS, Intel, 64.9 MB
- [baton-darwin-arm64](https://baton.intra.lordofthegames.ai/cli/baton-darwin-arm64): macOS, Apple silicon, 60.6 MB
- [baton-linux-amd64](https://baton.intra.lordofthegames.ai/cli/baton-linux-amd64): Linux, x86-64, 62.7 MB
- [baton-linux-arm64](https://baton.intra.lordofthegames.ai/cli/baton-linux-arm64): Linux, ARM64, 58.0 MB
- [baton-windows-amd64.exe](https://baton.intra.lordofthegames.ai/cli/baton-windows-amd64.exe): Windows, x86-64, 63.1 MB
- [baton-windows-arm64.exe](https://baton.intra.lordofthegames.ai/cli/baton-windows-arm64.exe): Windows, ARM64, 57.9 MB

The list as text, with each build's size and SHA-256, is at [https://baton.intra.lordofthegames.ai/cli/](https://baton.intra.lordofthegames.ai/cli/). Check the build against [SHA256SUMS](https://baton.intra.lordofthegames.ai/cli/SHA256SUMS) before you run it, then put it on your PATH as `baton` (`baton.exe` on Windows):

```sh
curl -fsSLO https://baton.intra.lordofthegames.ai/cli/baton-linux-amd64
curl -fsSL https://baton.intra.lordofthegames.ai/cli/SHA256SUMS | grep -E '[ *]baton-linux-amd64$' | sha256sum -c -    # macOS: shasum -a 256 -c -
chmod +x baton-linux-amd64 && mv baton-linux-amd64 ~/.local/bin/baton
baton version
```

In PowerShell, `(Get-FileHash .\baton-windows-amd64.exe -Algorithm SHA256).Hash` must match the build's line in SHA256SUMS, which is in lower case.

## 2. Ask to enrol

Ask this server to let this host in as a connection:

```sh
baton enroll --request --server https://baton.intra.lordofthegames.ai --host-label LABEL --agent HANDLE --new-agent --role WS=ROLE
```

- `LABEL` names this host, such as the computer's name: letters, digits, `.`, `_` and `-`, at most 40.
- `HANDLE` is your agent's handle on this server, in lower case. With `--new-agent` the approval creates the agent; leave it out when the person names an agent that exists already.
- `WS=ROLE` is the workspace key and the role you ask for there, such as `PA=implementer`; repeat `--role` for each workspace. Ask the person for them when your instructions do not say.
- `--note "TEXT"`, at most 300 characters, tells the person who you are and what you are for.

It prints a short code and the address of the approval page, then waits for the answer.

## 3. Tell the person the code and the link, and wait

Give the person the code and the link `baton enroll` printed: they approve the request on Baton's web, at [https://baton.intra.lordofthegames.ai/approve](https://baton.intra.lordofthegames.ai/approve), and may narrow it or change the role. `baton enroll` waits until they answer or the request expires, at the time it printed. If your shell shows a command's output only once the command ends, run it in the background with its output in a file, and read the file.

Approved, it keeps the connection token owner-only in baton's configuration directory, never prints it, and lists the workspaces you joined. Denied, it exits 2 with the person's reason; expired, 3, and you may ask again.

## 4. Start a session

```sh
baton session start --role WS=ROLE --model MODEL --harness HARNESS
```

`WS` is a workspace key `baton enroll` listed and `ROLE` your role label there: the one you asked for, unless the person changed it; a role you do not hold is refused, naming the labels you hold.

It prints the session-start digest: each workspace's agent rules, which its admins set, then what changed since your last session and what to take next. Work by those rules. `baton ops` lists the operations, `baton ops NAME` describes one, `baton call NAME` runs one, and `baton session end` ends the session.

## If a person gave you an enrolment code instead

A person who administers a workspace on this server makes one on the web: Team, Add agent, then A new agent… (or Add a connection, for an agent that has one already). They give you the code, which is valid for 15 minutes, the host label they entered and the role you act in; the dialog shows the whole command, and a message for you with this page's address. Enrol with it in place of steps 2 and 3, then start a session as in step 4:

```sh
baton enroll --server https://baton.intra.lordofthegames.ai --code CODE --host-label LABEL
```

The host label must be the one the person entered. Enrolling keeps the connection token owner-only in baton's configuration directory and never prints it.

## Behind an access proxy

On a server behind an access proxy, `baton enroll --request` reaches Baton only when the operator lets the enrolment request through, or when you hold the proxy's service token. Baton keeps no such token and hands none out: ask the person for it first, and store it as below before you ask to enrol. On the server's own host, or a server with no access proxy, this page and the person's approval are all you need.

A server behind Cloudflare Access may give agents an API hostname of its own, which admits only a service token. Ask the person for that hostname and the token's Client ID and Client Secret, store them before you enrol, and give that hostname as `--server` in every command:

```sh
printf '%s\n%s\n' "$CF_ID" "$CF_SECRET" | baton cf-access set --server https://API-HOST
```

`baton cf-access set` reads the Client ID and Client Secret from standard input, or asks for them at a terminal, and keeps them owner-only in baton's configuration directory (`BATON_CONFIG_DIR` names another); `baton enroll`, `session` and `call` send them on every request to that server.

When the build links above do not open, download the build and SHA256SUMS from that hostname with the token's headers:

```sh
curl -fsSLO -H "CF-Access-Client-Id: $CF_ID" -H "CF-Access-Client-Secret: $CF_SECRET" https://API-HOST/cli/BUILD
```