# Multi-Agent Forgejo Infrastructure

Setting up a self-hosted Forgejo instance for multi-agent teams. Each agent host gets its own machine user, SSH key, and scoped permissions. No shared credentials.

## Architecture

```
Forgejo (code.example.org:2222)
├── user: admin (bootstrap only)
├── user: agent-1 (write all repos, browser UI for PR review)
├── user: agent-2 (write all repos, SSH only)
└── user: agent-3 (write all repos, SSH only)

Vaultwarden (vault.example.org)
└── org: ProjectName
    ├── collection: agent-secrets (day-to-day passwords, tokens)
    ├── collection: bootstrap (admin tokens, setup keys)
    └── collection: deploy (deploy secrets)
```

## Setup Order

### 1. Create repos via API

Forgejo API needs a token with: `write:repository`, `write:user`, `write:organization`.

```bash
curl -X POST "https://<forgejo>/api/v1/user/repos" \
  -H "Authorization: token <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"...","private":false}'
```

### 2. Create machine users via admin API

Requires `write:admin` scope on the token.

- Untick "require password change" for SSH-only users.
- Keep it ticked for users that need browser access (e.g. Hermes for PR review).
- Emails: use per-agent aliases for audit trail.

### 3. Register SSH keys via admin API

Keys registered under the admin account get credited to the admin, not the machine user. Always use the admin API endpoint for the target user:

```bash
# WRONG — adds to admin's keys
curl -X POST "https://<forgejo>/api/v1/user/keys" ...

# CORRECT — adds to target user
curl -X POST "https://<forgejo>/api/v1/admin/users/<username>/keys" \
  -H "Authorization: token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"key":"ssh-ed25519 AAA...","title":"<username>@<host>","read_only":false}'
```

### 4. Set repo collaborators

```bash
curl -X PUT "https://<forgejo>/api/v1/repos/<owner>/<repo>/collaborators/<user>" \
  -H "Authorization: token <token>" \
  -H "Content-Type: application/json" \
  -d '{"permission":"write"}'
```

HTTP 204 = success. Requires `write:repository` on the token.

### 5. SSH config per host

```ssh-config
Host code.example.org
    HostName code.example.org
    User git
    Port 2222
    IdentityFile ~/.ssh/forgejo-<username>
    IdentitiesOnly yes
```

### 6. Bootstrap token lifecycle

Create → use for setup → **delete immediately after**.

API token deletion is not exposed externally on Forgejo. Delete manually at `https://<forgejo>/user/settings/applications`. Day-to-day git operations use SSH keys only — no tokens needed.

## Agent Self-Serve Doc

After initial setup, agents on new hosts can self-bootstrap by reading a FORGEJO-SETUP.md doc in the repo. Template at `templates/FORGEJO-SETUP.md`.

## Vaultwarden Integration

See `references/vaultwarden-bw-cli.md` for the full `bw` CLI workflow: login→unlock→session→lock pattern, collection management, and quirks.