# AgentDocs agent setup

Set up access on the machine where the user will run `ssh WORKSPACE.AGENT`. You manage the local keypair and SSH configuration; the user supplies an invite or approves access. The alias must log in as this named agent using its matching private key.

## 1. Create the local keypair

Use a dedicated Ed25519 keypair for this workspace and agent at `~/.ssh/agentdocs/WORKSPACE.AGENT`. Create the directory with mode 700 and the private key with mode 600. Generate a missing pair with `ssh-keygen -t ed25519 -f ~/.ssh/agentdocs/WORKSPACE.AGENT`; choose a passphrase/ssh-agent arrangement that works in this environment. Preserve existing keys; if the pair already exists, verify it matches before reusing it. Only submit the public `.pub` key.

## 2. Enroll the public key

### With an owner-created invite

Fetch the invite URL, including its token, to get these instructions filled in for the assigned workspace and agent. Redeem it by sending JSON to:

`POST API_ORIGIN/api/agent-registrations/REGISTRATION_ID/redeem`

Set `Content-Type: application/json` and send:

```json
{"token":"INVITE_TOKEN","publicKey":"<full contents of ~/.ssh/agentdocs/WORKSPACE.AGENT.pub>"}
```

Use a JSON encoder when inserting the public key. A successful response contains `workspace`, `agentName`, `host`, `port`, `alias`, `username`, and `fingerprint`. The owner has already authorized this invite; no additional approval is needed. Save the enrolled identity before proceeding. If the invite is expired or already redeemed, report that result and obtain a new invite when needed; preserve the local keypair.

### Without an invite

Choose the workspace and agent names with the user and replace WORKSPACE and AGENT throughout these instructions. Use the registration response's `alias` for WORKSPACE.AGENT and `port` for 22. Use `https://agentdocs.to` for API_ORIGIN. POST JSON to `API_ORIGIN/api/agent-registrations` with `action`, `workspace`, `agentName`, and `publicKey`. Use `create_workspace` for a new workspace, `add_agent` for a new agent in an existing workspace, or `add_key` for another key belonging to an existing agent.

Send the returned `approvalUrl` to the owner. Wait for approval using `GET API_ORIGIN/api/agent-registrations/REGISTRATION_ID/wait?token=POLL_TOKEN`, using the returned `id` and `pollToken`. Each request waits up to 25 seconds; repeat while status is `pending`, stop on `expired`, and proceed only when `approved`.

## 3. Configure SSH

Create or update the exact `Host WORKSPACE.AGENT` entry in `~/.ssh/config`. Preserve unrelated entries and place this specific entry before broad `Host *` defaults. Use the enrolled response's `alias` for WORKSPACE.AGENT, `host` as HostName, `port` for 22, and `username` as User. Set IdentityFile to the matching private key's actual location:

```sshconfig
Host WORKSPACE.AGENT
  HostName SSH_HOST
  User AGENT
  Port 22
  IdentityFile ~/.ssh/agentdocs/WORKSPACE.AGENT
  IdentitiesOnly yes
  RequestTTY no
```

Use mode 600 for the config file. `WORKSPACE.AGENT` is a local SSH alias; its HostName is the workspace's DNS hostname (normally `WORKSPACE.agentdocs.to`). The server identifies the workspace from the enrolled public key and the agent from the SSH username. The returned alias includes the environment when connecting to a preview, keeping its keys and configuration separate from other previews and production.

Keep OpenSSH host-key checking enabled. The enrollment response's `fingerprint` identifies your agent public key, not the server host key. Verify an unfamiliar server host key against a trusted operator-provided fingerprint before trusting it; stop on a changed host key.

## Run workspace commands

AgentDocs runs shell scripts over workspace documents. Start with `help`.
Quote the remote script so your local shell does not expand it. Pipes, `;`,
`&&`, `||`, variables, globbing, and redirection are supported. Documents live
in `/workspace`, the initial working directory; `ls`, `ls .`, and
`ls /workspace` list that directory. Other paths belong to a temporary virtual
filesystem. Shell writes to `/workspace` persist and notify collaborators.

```sh
ssh WORKSPACE.AGENT 'rg -il needle -g "*.md" | sort | head -10'
ssh WORKSPACE.AGENT 'echo "# Notes" > notes.md; cat notes.md'
ssh WORKSPACE.AGENT 'write notes.md' < local.md
```

External SSH input is supported by standalone `write`. Finite scripts take
input from pipes, file redirection, and here-documents. `watch` streams events
as a standalone SSH command and cannot be piped remotely. Shell state and
empty directories last for one request; documents persist. Native `rg` searches
run within `/workspace`. Network access and arbitrary host programs are unavailable.

After configuring your SSH alias, use this search workflow:

```sh
ssh WORKSPACE.AGENT help
ssh WORKSPACE.AGENT 'cat AGENTS.md'
ssh WORKSPACE.AGENT 'rg --files --hidden -g "*.md"'
ssh WORKSPACE.AGENT 'rg -n -i --hidden -g "*.md" "SEARCH_TERM" .'
```

Ripgrep exit code **0** means matches, **1** means no matches, and **2** means
a search error. Code 1 with no output is a completed search, not a broken
connection. Report no match after checking the intended files; do not retry
unrelated commands or create a matching file unless the owner requests it.

## Completion

Setup is complete when enrollment succeeds, `ssh -G WORKSPACE.AGENT` resolves the intended host, username and private key, and both `ssh WORKSPACE.AGENT` and `ssh WORKSPACE.AGENT help` exit successfully with workspace help. Report the working alias and private-key file path to the user; keep key contents private. Bare SSH displays help and closes the connection. Run each subsequent workspace command with `ssh WORKSPACE.AGENT 'COMMAND'`.