Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 29 additions & 13 deletions ops/kin/host/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,19 +168,35 @@ What a worker does get: its own checkouts and worktrees in `/home/kin-worker`, i

### Set up workers

Steps marked **root** need sudo. **account** marks one the owner creates outside the host. Run the installer only from `/root/kin-ops` (see [Install](#install)); it refuses a clone that isn't root-owned. After the first run, `/usr/local/sbin/kin-worker` (root-owned) does the rest. Root never writes, chowns or chmods anything under `/home/kin-worker`: the installer does that as kin-worker, so a symlink a worker plants there reaches only what kin-worker could change anyway.

1. **root:** `sudo git -C /root/kin-ops pull --ff-only` (the clone from step 0 of [Install](#install)).
2. **root:** `sudo /root/kin-ops/ops/kin/host/kin-worker.sh`. It creates `kin-worker` (home mode 700, not in group `kin`), sets `/home/kin` to mode 700, installs `/usr/local/sbin/kin-worker`, the units `kin-worker-server.service` and `kin-worker-link.{service,timer}`, and `/etc/sudoers.d/kin-worker`, which lets `kin` run exactly `systemctl stop`, `start` and `try-restart` on the worker unit and `kin-worker upload-pack <path>`. As kin-worker, it turns on Linked environments in the worker environment's settings and writes `~kin-worker/.claude/settings.json` with only the gateway URL and an `apiKeyHelper` that reads `~kin-worker/.config/kin-worker/gateway-key`. Then it starts the worker server on `127.0.0.1:3874` if Kin has a build and isn't paused. The gateway URL is `KIN_WORKER_GATEWAY_URL` when set (`sudo KIN_WORKER_GATEWAY_URL=https://... /root/kin-ops/...`), else the `ANTHROPIC_BASE_URL` in kin's Claude settings; nothing else is read from kin's file. A changed unit is reloaded and the server restarted. It prints a checklist; the first run fails it until the steps below are done. `--dry-run` changes nothing.
3. **root:** tools in kin-worker's own home, like kin's (step 2 of [Install](#install)): `sudo -iu kin-worker`, then `curl https://mise.run | sh`, `mise use -g node@<engines.node>`, `npm i -g @anthropic-ai/claude-code @openai/codex`. `git`, `gh`, `curl`, `python3`, `sqlite3`, iproute2 (`ss`) and util-linux (`nsenter`, `setpriv`) come from the distribution, system-wide. The worker unit's start check and `check`'s probes run only those root-owned copies, never anything on the worker's `PATH`.
4. **account, then root: Claude.** Create a gateway key for kin-worker alone, never kin's or yours. Write it as kin-worker: `sudo kin-worker run -- sh -c 'umask 077 && mkdir -p ~/.config/kin-worker && cat > ~/.config/kin-worker/gateway-key' < <key file>`, shred the file, then `sudo kin-worker run -- claude -p ok` should answer.
5. **account, then root: Codex.** Use a separate OpenAI account or an API key with a spending cap, never the owner's login or token. `sudo kin-worker run -- codex login` and sign in to that account, or `sudo kin-worker run -- codex login --with-api-key < <key file>`.
6. **GitHub: Kin publishes, workers only read.** Before you list any repo in `KIN_GITHUB_REPOS`, that repo's default branch must carry the CI guard: every workflow job that reads a secret skips `kin/worker/*` heads (`if: ${{ !startsWith(github.head_ref, 'kin/worker/') }}`, or `github.event.workflow_run.head_branch` for `workflow_run` jobs; see this repo's `.github/workflows`). A worker's PR runs that repo's workflows on the worker's code, so without the guard a worker gets the repo's secrets. The Kin GitHub App must **not** have the **Workflows** permission: Kin's refusal of `.github` changes is backed by GitHub refusing the push. Check it on GitHub under Settings → Developer settings → GitHub Apps → the Kin App → Permissions & events → Repository permissions, where Workflows must read "No access", and on each installation's Configure page, which must not list workflows. On kin-server, set `KIN_GITHUB_APP_ID` (the Kin GitHub App, approvals spec section 10), install the App on every worker repo, and list those repos in `KIN_GITHUB_REPOS` in `~kin/.t3/service.env`: Kin mints its `server` push token only for those. Public repos need nothing on the worker side; Kin's server publishes for workers. For a private repo, **account, then root:** a fine-grained token limited to the worker repos with **Contents: read** and nothing else, never a token with write, never the owner's, kin's or the App's. Then `sudo kin-worker run -- gh auth login --with-token < <token file>` (shred the file after) and `sudo kin-worker run -- gh auth setup-git`. No bot account needs write access to anything. **Hosts set up under the earlier steps,** where workers pushed as a bot account: delete that bot's fine-grained token (the bot's Settings → Developer settings → Personal access tokens → Fine-grained tokens) and remove the bot's Write access on the worker repos, then `sudo kin-worker run -- gh auth logout` and, for private repos, log in again with the read-only token above. `sudo kin-worker check` fails while kin-worker still holds a token that can push. The App's key lives in kin's keyring: set that up first ([GitHub App keyring](#github-app-keyring)).
7. **Disk. root:** put `/home/kin-worker` on its own filesystem, or give `kin-worker` a disk quota, so a worker filling its home can't fill the disk kin-server, its database and its backups live on.
8. **Projects. root:** for each of the lead's worker projects, clone the same repository into the worker environment and register it there: `sudo kin-worker run -- git clone https://github.com/<owner>/<repo> /home/kin-worker/projects/<repo>`, then `sudo kin-worker run t3 project add /home/kin-worker/projects/<repo> --base-dir /home/kin-worker/.t3`. Kin matches a lead's worker project to the worker environment's project with the same repository, so `kin lead create --worker-project` keeps naming this host's project.
9. **Linked environments on kin-server:** Settings → Labs → Linked environments, from any client.
10. **root:** `sudo kin-worker link`. Links kin-server to `http://127.0.0.1:3874` with full access and writes `KIN_WORKER_ENVIRONMENT_ID` into `~kin/.t3/service.env`. Restart kin-server at a quiet moment, as it says. A link lasts 30 days; `kin-worker-link.timer` renews it weekly.
11. **root:** `sudo git -C /root/kin-ops pull --ff-only && sudo /root/kin-ops/ops/kin/host/kin-worker.sh` again, then `sudo kin-worker check`. Every line must be ✓ before a lead goes to L2.
One command sets workers up. It does every step that needs no credential, asks on the terminal for the two that do, and ends with the isolation check. A private repository's read-only GitHub token for kin-worker is a separate step you do first (GitHub, under "Three things stay with you" below):

```bash
sudo git -C /root/kin-ops pull --ff-only
sudo /root/kin-ops/ops/kin/host/kin-worker.sh setup
```

Run it on a terminal (`ssh -t`), with nothing piped in: it refuses to start without one. Run it after Kin has a build ([Install](#install), step 3), and only from `/root/kin-ops`: it refuses a clone that isn't root-owned. Have these ready first; they are yours to create outside the host, and nothing else is asked for:

- **A Claude gateway key for kin-worker alone**, never kin's or yours. Setup takes it without echo and kin-worker writes it to `~kin-worker/.config/kin-worker/gateway-key` (mode 600). It is never printed, logged or put on a command line, and setup refuses kin's own key.
- **Optional: a Codex API key** on a separate OpenAI account with a spending cap, never the owner's login or token. Press Enter to skip it and workers use Claude only. To sign in to a ChatGPT account instead, skip it and run `sudo kin-worker run -- codex login` afterwards.

Before it changes anything it checks for Bash 4.4, GNU `stat` and `sed`, systemd 249 or later, a terminal, the `kin` user and Kin's build. Running it again keeps what is already there (users, units, settings, tools, the gateway key, checkouts and their registration), so use it to repair a host or to add a repository (`setup <owner>/<repo> ...`). Each run does pair and link kin-server again, as the weekly timer does, and asks for a Codex key again if Codex isn't signed in. It exits non-zero when a check fails or a repository couldn't be cloned or registered; the isolation check still runs in that case. `setup --dry-run` changes nothing. It never restarts kin-server. What it does, in order:

1. **Users, units and sandbox.** It creates `kin-worker` (home mode 700, not in group `kin`), sets `/home/kin` to mode 700, installs `/usr/local/sbin/kin-worker`, the units `kin-worker-server.service` and `kin-worker-link.{service,timer}`, and `/etc/sudoers.d/kin-worker`, which lets `kin` run exactly `systemctl stop`, `start` and `try-restart` on the worker unit and `kin-worker upload-pack <path>`. As kin-worker, it turns on Linked environments in the worker environment's settings and writes `~kin-worker/.claude/settings.json` with only the gateway URL and an `apiKeyHelper` that reads `~kin-worker/.config/kin-worker/gateway-key`. The worker server on `127.0.0.1:3874` starts once its tools are installed (step 2), if Kin has a build and isn't paused. The gateway URL is `KIN_WORKER_GATEWAY_URL` when set (`sudo KIN_WORKER_GATEWAY_URL=https://... /root/kin-ops/... setup`), else the `ANTHROPIC_BASE_URL` in kin's Claude settings; nothing else is read from kin's file. A changed unit is reloaded and the server restarted.
2. **Tools.** As kin-worker, inside the sandbox, it installs mise, the build's Node, Claude Code and Codex into kin-worker's own home, then starts the worker server. `git`, `gh`, `curl`, `python3`, `sqlite3`, iproute2 (`ss`) and util-linux (`nsenter`, `setpriv`) come from the distribution, system-wide. The worker unit's start check and `check`'s probes run only those root-owned copies, never anything on the worker's `PATH`.
3. **The two credentials**, as above, then `claude -p ok` as kin-worker to show the key works. The gateway key is compared with kin's before it is written, and setup stops without asking if it can't read kin's key to compare. Ctrl-C at a prompt turns echo back on and writes nothing.
4. **Linked environments on kin-server.** kin sets that one key in its own `settings.json`, which the server watches. If the file can't be parsed it is left alone and setup says to turn it on from a client: Settings → Labs → Linked environments.
5. **Projects.** For every repository Kin publishes to (`KIN_GITHUB_REPOS` and Kin's own) and any you name, kin-worker clones `https://github.com/<owner>/<repo>` into `/home/kin-worker/projects/<repo>` and registers it in the worker environment. Memory repositories are skipped. A lead starts work in a repository by name, and Kin matches the name to the checkout here by its GitHub remote. A private repository that kin-worker can't read yet is listed with ✗ and setup exits non-zero; give kin-worker the read-only token below, which setup doesn't ask for, and run setup again.
6. **The link.** Once the worker server answers on its port (up to a minute), `kin-worker link` links kin-server to `http://127.0.0.1:3874` with full access and, as kin, writes `KIN_WORKER_ENVIRONMENT_ID` into `~kin/.t3/service.env` (replaced whole, mode 600; created if missing). A link lasts 30 days; `kin-worker-link.timer` renews it weekly.
7. **`kin-worker check`.** Every line must be ✓ before leads start workers.

Three things stay with you. Do the GitHub one before setup, so its repositories are there to clone and `check` can pass:

- **Restart kin-server once, at a quiet moment,** so it reads the new `KIN_WORKER_ENVIRONMENT_ID`. Setup prints the command. Until then leads tell the owner the worker environment isn't set up.
- **GitHub: Kin publishes, workers only read.** Before you list any repo in `KIN_GITHUB_REPOS`, that repo's default branch must carry the CI guard: every workflow job that reads a secret skips `kin/worker/*` heads (`if: ${{ !startsWith(github.head_ref, 'kin/worker/') }}`, or `github.event.workflow_run.head_branch` for `workflow_run` jobs; see this repo's `.github/workflows`). A worker's PR runs that repo's workflows on the worker's code, so without the guard a worker gets the repo's secrets. The Kin GitHub App must **not** have the **Workflows** permission: Kin's refusal of `.github` changes is backed by GitHub refusing the push. Check it on GitHub under Settings → Developer settings → GitHub Apps → the Kin App → Permissions & events → Repository permissions, where Workflows must read "No access", and on each installation's Configure page, which must not list workflows. On kin-server, set `KIN_GITHUB_APP_ID` (the Kin GitHub App, approvals spec section 10), install the App on every worker repo, and list those repos in `KIN_GITHUB_REPOS` in `~kin/.t3/service.env`: Kin mints its `server` push token only for those. Public repos need nothing on the worker side; Kin's server publishes for workers. For a private repo, **account, then root:** a fine-grained token limited to the worker repos with **Contents: read** and nothing else, never a token with write, never the owner's, kin's or the App's. Then `sudo kin-worker run -- gh auth login --with-token < <token file>` (shred the file after) and `sudo kin-worker run -- gh auth setup-git`. No bot account needs write access to anything. **Hosts set up under the earlier steps,** where workers pushed as a bot account: delete that bot's fine-grained token (the bot's Settings → Developer settings → Personal access tokens → Fine-grained tokens) and remove the bot's Write access on the worker repos, then `sudo kin-worker run -- gh auth logout` and, for private repos, log in again with the read-only token above. `sudo kin-worker check` fails while kin-worker still holds a token that can push. The App's key lives in kin's keyring: set that up first ([GitHub App keyring](#github-app-keyring)).
- **Disk.** Put `/home/kin-worker` on its own filesystem, or give `kin-worker` a disk quota, so a worker filling its home can't fill the disk kin-server, its database and its backups live on. Setup says so when the two homes share a filesystem.

Root never writes, chowns or chmods anything under `/home/kin-worker`: setup does that as kin-worker, so a symlink a worker plants there reaches only what kin-worker could change anyway. The steps also run one at a time: `kin-worker.sh install` (step 1 alone, then a checklist of what is missing), `sudo kin-worker run -- <command>` for anything as kin-worker in the sandbox (`sudo kin-worker run t3 project add <path> --base-dir /home/kin-worker/.t3`), `sudo kin-worker link` and `sudo kin-worker check`.

### GitHub App keyring

Expand Down
Loading