diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d5d6773 --- /dev/null +++ b/.env.example @@ -0,0 +1,44 @@ +# .env: secrets for your fleet. `./fleet setup` fills this in. +# Never commit this file. +# +# There are no AI API keys here on purpose. Models run on your Claude and +# ChatGPT subscriptions, connected with `./fleet login claude` and +# `./fleet login chatgpt`; those logins live in the container volumes. + +# ── Generated by ./fleet setup ─────────────────────────────────────────────── +# Protects the OpenClaw Control UI and gateway API. +OPENCLAW_GATEWAY_TOKEN= +# Password for the Hermes dashboard (user: admin). +HERMES_DASHBOARD_PASSWORD= +# Postgres password for engram's database. +POSTGRES_PASSWORD= + +# ── Who is allowed to talk to your agents ─────────────────────────────────── +# Agents only answer these people in DMs; anyone else gets a pairing code you +# approve with `./fleet pair`. +OWNER_DISCORD_ID= +OWNER_TELEGRAM_ID= +# Phone number with country code, digits only (e.g. 447700900123). +OWNER_WHATSAPP_NUMBER= + +# ── Chat bots: one per agent, named after the agent id in fleet.yaml ──────── +# Discord: https://discord.com/developers/applications → New Application → Bot +# → Reset Token. Turn on "Message Content Intent". +# Telegram: message @BotFather → /newbot. +DISCORD_TOKEN_OPS= +DISCORD_TOKEN_BUILDER= +TELEGRAM_TOKEN_ASSISTANT= + +# ── session-warden alerts (optional) ──────────────────────────────────────── +# A Telegram bot + chat that receives fleet health alerts. +WARDEN_TELEGRAM_BOT_TOKEN= +WARDEN_TELEGRAM_CHAT_ID= + +# ── Advanced ──────────────────────────────────────────────────────────────── +# Image tag to run. Pin a release (e.g. 0.1.0) in production. +FLEETKIT_VERSION=latest +# Host ports. Bound to 127.0.0.1 only; reach them over SSH or a tunnel. +OPENCLAW_PORT=18789 +HERMES_DASHBOARD_PORT=9119 +FLEET_BOARD_PORT=8090 +ENGRAM_PORT=8080 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..be4e9d2 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,60 @@ +name: ci + +on: + pull_request: + push: + branches: [main, staging] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: shellcheck + run: | + shellcheck -S warning fleet install.sh \ + images/fleet/rootfs/usr/local/bin/fleet-entrypoint \ + images/fleet/rootfs/usr/local/bin/fleet-engram-mcp \ + images/fleet/rootfs/usr/local/bin/systemctl \ + images/engram/fleet-engram-tokens.sh + - name: fleet-init compiles + run: python3 -m py_compile images/fleet/rootfs/opt/fleetkit/bin/fleet-init + - name: compose config + run: | + cp .env.example .env + cp fleet.example.yaml fleet.yaml + sed -i 's/^OPENCLAW_GATEWAY_TOKEN=$/OPENCLAW_GATEWAY_TOKEN=ci/; s/^HERMES_DASHBOARD_PASSWORD=$/HERMES_DASHBOARD_PASSWORD=ci/' .env + COMPOSE_PROFILES=memory docker compose config --quiet + + boot: + runs-on: ubuntu-latest + needs: lint + steps: + - uses: actions/checkout@v4 + - name: boot the fleet + run: | + cp fleet.example.yaml fleet.yaml + cp .env.example .env + for k in OPENCLAW_GATEWAY_TOKEN HERMES_DASHBOARD_PASSWORD POSTGRES_PASSWORD; do + sed -i "s/^$k=\$/$k=$(openssl rand -hex 16)/" .env + done + export COMPOSE_PROFILES=memory + docker compose build + docker compose up -d + - name: wait for healthy gateway + run: | + export COMPOSE_PROFILES=memory + for i in $(seq 60); do + [ "$(docker inspect -f '{{.State.Health.Status}}' fleet-openclaw-1 2>/dev/null)" = healthy ] && break + sleep 5 + done + docker compose ps -a + docker compose logs init + test "$(docker inspect -f '{{.State.ExitCode}}' fleet-init-1)" = 0 + curl -fsS http://127.0.0.1:18789/ >/dev/null + curl -fsS http://127.0.0.1:8090/ >/dev/null + curl -fsS http://127.0.0.1:8080/health + test "$(docker inspect -f '{{.State.Status}}' fleet-hermes-1)" = running + - name: logs on failure + if: failure() + run: COMPOSE_PROFILES=memory docker compose logs --tail 200 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..a101447 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,49 @@ +name: publish + +on: + push: + branches: [main] + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + packages: write + +jobs: + image: + runs-on: ubuntu-latest + strategy: + matrix: + include: + - name: fleetkit + context: images/fleet + - name: fleetkit-engram + context: images/engram + steps: + - uses: actions/checkout@v4 + - uses: docker/setup-qemu-action@v3 + - uses: docker/setup-buildx-action@v3 + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/ani-hq/${{ matrix.name }} + tags: | + type=raw,value=latest,enable={{is_default_branch}} + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=sha,format=short + - uses: docker/build-push-action@v6 + with: + context: ${{ matrix.context }} + platforms: linux/amd64,linux/arm64 + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha,scope=${{ matrix.name }} + cache-to: type=gha,mode=max,scope=${{ matrix.name }} diff --git a/.gitignore b/.gitignore index b8c5a42..c9d08b2 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ fleet.yaml backups/ *.log .DS_Store +__pycache__/ diff --git a/README.md b/README.md index 999905e..6d1717b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,81 @@ # fleetkit -A self-hosted AI agent fleet in one `docker compose up`. +Your own AI agent fleet on one server. It runs on the Claude and ChatGPT subscriptions you already pay for, with no API keys, and you talk to it on Discord, Telegram or WhatsApp. + +```bash +curl -fsSL https://raw.githubusercontent.com/Ani-HQ/fleetkit/main/install.sh | bash +cd ~/fleetkit +./fleet setup # a few questions: name, timezone, agents, chat bots +./fleet up # start everything +./fleet login claude # and/or: ./fleet login chatgpt +``` + +DM your bot. That's it. + +## What you get + +| Piece | What it does | +| --- | --- | +| [OpenClaw](https://github.com/openclaw/openclaw) | Gateway for your main agents. Starts with **ops** and **builder**. | +| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | A second harness. Starts with **assistant**. | +| [engram](https://github.com/Ani-HQ/engram) + gbrain | Shared long-term memory every agent reads and writes, over MCP. | +| [session-warden](https://github.com/Ani-HQ/session-warden) | Keeps agents healthy: rotates bloated sessions, guards usage limits, nightly reflection, weekly reviews. | +| Fleet board | A live page showing what each agent is doing. | + +The agents are generic starters. Rename them, change their roles, or add more in `fleet.yaml`, then run `./fleet up` again. + +## What you need + +- A Linux server with **4 GB RAM** and 2 vCPUs (Ubuntu 22.04+ or Debian 12+). Any cloud works. See [docs/deploy.md](docs/deploy.md). +- **Claude Pro/Max** or **ChatGPT Plus/Pro** (or both). See [docs/subscriptions.md](docs/subscriptions.md). +- A bot for each agent on Discord or Telegram, or a spare WhatsApp number. See [docs/channels.md](docs/channels.md). + +**No API keys.** Every model call goes through your subscription login, the same way the Claude and Codex apps do. If you have both subscriptions, agents switch to the other one when they hit a usage limit. + +## Can I deploy it to Vercel? + +No. Vercel runs short-lived functions. A fleet needs processes that stay up all the time, a disk that persists between restarts, and scheduled jobs. Use any VPS or cloud VM (from about $5/month). Railway support is planned. + +## Everyday commands + +``` +./fleet status what's running +./fleet logs openclaw follow logs (openclaw, hermes, engram, init) +./fleet ui open the dashboards (over an SSH tunnel) +./fleet pair discord ABC approve someone who messaged an agent +./fleet whatsapp ops pair WhatsApp by QR code +./fleet backup snapshot config, logins, sessions and memory +./fleet update pull the latest fleetkit and restart +./fleet openclaw OpenClaw CLI inside the fleet +./fleet hermes Hermes CLI for one agent +``` + +## How it fits together + +``` +fleet.yaml + .env + │ + ▼ + init ──────────── renders OpenClaw config, Hermes profiles, warden schedule + │ + ├── openclaw gateway + session-warden (cron) + fleet board :18789 :8090 + ├── hermes gateway + dashboard :9119 + └── engram memory server (Postgres + pgvector) :8080 +``` + +- `fleet.yaml` is the only file you edit. `init` turns it into native config every time you run `./fleet up`. +- Files the agents write themselves (memory notes, personas after first boot) are never overwritten. +- All ports are bound to `127.0.0.1`. Reach the dashboards over SSH. See [docs/security.md](docs/security.md). +- Data lives in Docker volumes. `./fleet backup` saves all of it. + +## Docs + +- [Deploy to a cloud](docs/deploy.md) +- [Connect subscriptions](docs/subscriptions.md) +- [Connect Discord, Telegram, WhatsApp](docs/channels.md) +- [Security](docs/security.md) +- [Upgrading and backups](docs/upgrading.md) + +## License + +MIT diff --git a/cloud-init.yaml b/cloud-init.yaml new file mode 100644 index 0000000..2d2bb03 --- /dev/null +++ b/cloud-init.yaml @@ -0,0 +1,15 @@ +#cloud-config +# Paste into "user data" when creating an Ubuntu server (Hetzner, DigitalOcean, +# AWS, GCP, Oracle, Linode, Vultr...). It installs Docker and fleetkit for the +# default user. Then SSH in and run: cd ~/fleetkit && ./fleet setup && ./fleet up +package_update: true +packages: [git, curl, openssl, python3, ca-certificates] +runcmd: + - curl -fsSL https://get.docker.com | sh + - systemctl enable --now docker + - | + u=$(getent passwd 1000 | cut -d: -f1) + [ -n "$u" ] || u=root + [ "$u" = root ] || usermod -aG docker "$u" + h=$(getent passwd "$u" | cut -d: -f6) + sudo -u "$u" git clone --depth 1 https://github.com/Ani-HQ/fleetkit.git "$h/fleetkit" diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..aa58dc3 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,134 @@ +# fleetkit: an AI agent fleet in one `docker compose up`. +# +# Use `./fleet up` rather than calling compose directly; it validates +# fleet.yaml, picks the memory profile and pulls or builds images first. +# +# Boot order: +# db → engram → engram-tokens (mint memory tokens, once) +# → init (render fleet.yaml into OpenClaw + Hermes config) +# → openclaw (gateway + session-warden + fleet board), hermes + +name: fleet + +x-fleet-image: &fleet-image + image: ghcr.io/ani-hq/fleetkit:${FLEETKIT_VERSION:-latest} + build: + context: ./images/fleet + +x-fleet-volumes: &fleet-volumes + - openclaw:/home/node/.openclaw + - hermes:/home/node/.hermes + - claude:/home/node/.claude + - warden:/opt/session-warden/state + - fleet-secrets:/run/fleet-secrets + - ./fleet.yaml:/etc/fleetkit/fleet.yaml:ro + +services: + init: + <<: *fleet-image + command: ["init"] + user: root + env_file: .env + volumes: *fleet-volumes + depends_on: + engram-tokens: + condition: service_completed_successfully + required: false + restart: "no" + + openclaw: + <<: *fleet-image + command: ["gateway"] + env_file: .env + environment: + ENGRAM_HOST: http://engram:8080 + volumes: *fleet-volumes + ports: + - "127.0.0.1:${OPENCLAW_PORT:-18789}:18789" + - "127.0.0.1:${FLEET_BOARD_PORT:-8090}:8090" + depends_on: + init: + condition: service_completed_successfully + restart: unless-stopped + init: false + stop_grace_period: 40s + + hermes: + image: nousresearch/hermes-agent:${HERMES_VERSION:-v2026.9.24} + command: ["gateway", "run"] + environment: + # Same uid as the fleet image's `node` user, so both containers can read + # and write the shared Hermes volume. + HERMES_UID: "1000" + HERMES_GID: "1000" + HERMES_DASHBOARD: "1" + HERMES_DASHBOARD_BASIC_AUTH_USERNAME: admin + HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: ${HERMES_DASHBOARD_PASSWORD:?run ./fleet setup} + HERMES_DASHBOARD_BASIC_AUTH_SECRET: ${OPENCLAW_GATEWAY_TOKEN:?run ./fleet setup} + volumes: + - hermes:/opt/data + ports: + - "127.0.0.1:${HERMES_DASHBOARD_PORT:-9119}:9119" + depends_on: + init: + condition: service_completed_successfully + restart: unless-stopped + + db: + image: pgvector/pgvector:pg16 + profiles: [memory] + environment: + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-engram} + volumes: + - engram-pg:/var/lib/postgresql/data + - ./images/engram/create-dbs.sql:/docker-entrypoint-initdb.d/create-dbs.sql:ro + healthcheck: + test: ["CMD-SHELL", "pg_isready -U postgres"] + interval: 3s + timeout: 3s + retries: 30 + restart: unless-stopped + + engram: + image: ghcr.io/ani-hq/fleetkit-engram:${FLEETKIT_VERSION:-latest} + build: + context: ./images/engram + profiles: [memory] + environment: &engram-env + ENGRAM_DB_URL_TEMPLATE: postgresql://postgres:${POSTGRES_PASSWORD:-engram}@db:5432/__DB__ + ENGRAM_PUBLIC_URL: http://127.0.0.1:${ENGRAM_PORT:-8080} + volumes: + - engram-homes:/gbrain-homes + ports: + - "127.0.0.1:${ENGRAM_PORT:-8080}:8080" + depends_on: + db: + condition: service_healthy + healthcheck: + test: ["CMD", "bun", "-e", "const r=await fetch('http://127.0.0.1:8080/health');process.exit(r.ok?0:1)"] + interval: 5s + timeout: 5s + retries: 30 + start_period: 20s + restart: unless-stopped + + engram-tokens: + image: ghcr.io/ani-hq/fleetkit-engram:${FLEETKIT_VERSION:-latest} + profiles: [memory] + entrypoint: ["/bin/sh", "/usr/local/bin/fleet-engram-tokens"] + environment: *engram-env + volumes: + - fleet-secrets:/run/fleet-secrets + depends_on: + engram: + condition: service_healthy + restart: "no" + +volumes: + openclaw: + hermes: + claude: + warden: + fleet-secrets: + engram-pg: + engram-homes: diff --git a/docs/channels.md b/docs/channels.md new file mode 100644 index 0000000..05168aa --- /dev/null +++ b/docs/channels.md @@ -0,0 +1,54 @@ +# Connect Discord, Telegram and WhatsApp + +Each agent gets its own bot, so you can tell them apart. Set channels per agent in `fleet.yaml`: + +```yaml +agents: + - id: ops + channels: [discord] +``` + +Tokens go in `.env`, named after the agent id: `DISCORD_TOKEN_OPS`, `TELEGRAM_TOKEN_ASSISTANT`. `./fleet setup` asks for them. After editing by hand, run `./fleet up`. + +## Who can talk to your agents + +Agents answer **you** in DMs. Set your IDs in `.env` (setup asks): + +- `OWNER_DISCORD_ID`: Discord → Settings → Advanced → Developer Mode on. Right-click your name → Copy User ID. +- `OWNER_TELEGRAM_ID`: message [@userinfobot](https://t.me/userinfobot). +- `OWNER_WHATSAPP_NUMBER`: digits with country code, e.g. `447700900123`. + +If you leave an ID blank, anyone who DMs the bot gets a pairing code. Approve it with `./fleet pair `. + +## Discord + +1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) → **New Application**. Name it after the agent. +2. **Bot** → **Reset Token** → copy it into `.env` as `DISCORD_TOKEN_`. +3. On the same page, turn on **Message Content Intent**. +4. **OAuth2 → URL Generator**: tick `bot` and `applications.commands`. Under bot permissions, tick Send Messages, Read Message History, Add Reactions, Attach Files, Use Slash Commands. Open the URL and add the bot to your server. +5. `./fleet up`. DM the bot, or mention it in a server channel. + +Repeat for each Discord agent. + +## Telegram + +1. Message [@BotFather](https://t.me/BotFather) → `/newbot` → pick a name. +2. Copy the token into `.env` as `TELEGRAM_TOKEN_`. +3. `./fleet up`. Open your bot in Telegram and press Start. + +To use a bot in a group, turn off privacy mode: BotFather → `/setprivacy` → Disable. + +## WhatsApp + +WhatsApp links to a real phone number, like WhatsApp Web. Use a spare number, not your personal one: the agent reads and replies to everything that number receives. + +1. Set `channels: [whatsapp]` on one agent and `./fleet up`. +2. `./fleet whatsapp `. A QR code appears. +3. On the phone with the spare number: WhatsApp → Settings → Linked devices → Link a device → scan. +4. Message that number from your own phone. + +You can give WhatsApp to one OpenClaw agent and one Hermes agent at most. + +## Warden alerts (optional) + +session-warden can send health alerts to Telegram. Create one more bot with BotFather, send it a message, then set `WARDEN_TELEGRAM_BOT_TOKEN` and `WARDEN_TELEGRAM_CHAT_ID` (your user ID) in `.env`. diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000..78640ed --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,75 @@ +# Deploy to a cloud + +fleetkit runs on any Linux server with Docker. Pick a provider, create an Ubuntu 24.04 server with **4 GB RAM** and 2 vCPUs, then either: + +- paste [`cloud-init.yaml`](../cloud-init.yaml) into the "user data" box when you create it, or +- SSH in and run the installer: + + ```bash + curl -fsSL https://raw.githubusercontent.com/Ani-HQ/fleetkit/main/install.sh | bash + ``` + +Then: + +```bash +cd ~/fleetkit +./fleet setup +./fleet up +./fleet login claude # and/or chatgpt +``` + +You do not need to open any inbound ports besides SSH. Discord, Telegram and WhatsApp connect outbound. + +## Providers + +| Provider | Size that fits | Roughly | +| --- | --- | --- | +| Hetzner Cloud | CX32 / CAX21 (4 GB) | €7/mo | +| DigitalOcean | Basic 4 GB | $24/mo | +| Vultr | Regular 4 GB | $20/mo | +| Linode (Akamai) | Shared 4 GB | $24/mo | +| AWS Lightsail | 4 GB | $24/mo | +| AWS EC2 | t4g.medium (arm64) | ~$25/mo | +| Google Cloud | e2-medium | ~$25/mo | +| Oracle Cloud | Ampere A1, 4 OCPU / 24 GB | free tier | + +Both amd64 and arm64 work. + +### Hetzner + +Create server → Ubuntu 24.04 → CAX21 → add your SSH key → **Cloud config**: paste `cloud-init.yaml` → Create. SSH in as `root`. + +### DigitalOcean + +Create → Droplets → Ubuntu 24.04 → Basic, 4 GB → **Advanced options → Add initialization scripts**: paste `cloud-init.yaml`. + +### AWS (EC2 or Lightsail) + +Launch an Ubuntu 24.04 instance. Under **Advanced details → User data**, paste `cloud-init.yaml`. The security group only needs SSH (22) inbound. SSH in as `ubuntu`. + +### Google Cloud + +```bash +gcloud compute instances create fleet \ + --machine-type=e2-medium --image-family=ubuntu-2404-lts-amd64 \ + --image-project=ubuntu-os-cloud --boot-disk-size=30GB \ + --metadata-from-file=user-data=cloud-init.yaml +gcloud compute ssh fleet +``` + +### Oracle Cloud free tier + +Create instance → Ubuntu 24.04 → shape VM.Standard.A1.Flex (4 OCPU, 24 GB) → **Show advanced options → Management → cloud-init script**: paste `cloud-init.yaml`. SSH in as `ubuntu`. + +### Your own machine + +Any Mac or Linux box with Docker works too: `git clone https://github.com/Ani-HQ/fleetkit && cd fleetkit && ./fleet setup && ./fleet up`. Agents only run while it's on. + +## Not supported + +- **Vercel, Netlify, Cloudflare Pages and other serverless hosts.** The fleet needs long-running processes, a persistent disk and scheduled jobs. +- **Railway** is planned as a one-click template. + +## Disk and memory + +The full fleet idles at about 1.4 GB RAM and climbs while agents work, which is why 4 GB is the minimum. Leave 20 GB of disk for images, sessions and backups. diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..1c627c7 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,27 @@ +# Security + +Agents can run commands and read files inside their containers, and they act with your subscription logins. Treat the server like a laptop you've left logged in. + +## Defaults + +- **No public ports.** Every dashboard and API is bound to `127.0.0.1`. Use `./fleet ui` for the SSH tunnel command. +- **DMs are owner-only.** Agents only answer the IDs in `.env`. Anyone else needs a pairing code you approve. +- **Generated secrets.** `./fleet setup` creates the gateway token, dashboard password and database password with `openssl rand`. `.env` is `chmod 600` and gitignored. +- **Memory tokens.** Each service gets its own engram token, minted on first boot and stored only in the `fleet-secrets` volume. +- **Non-root agents.** OpenClaw and Hermes run as uid 1000. + +## Recommendations + +- Use SSH keys, turn off password login, and enable a firewall that only allows SSH (`ufw allow OpenSSH && ufw enable`). +- Give WhatsApp a spare number. The agent sees everything sent to it. +- In Discord, add bots to a private server or private channels. Server channels are open to everyone in them by default. +- Pin `FLEETKIT_VERSION` to a release in `.env` and update on purpose. +- Run `./fleet backup` before updates, and copy `backups/` off the server. Backups contain your logins: store them like passwords. + +## If you want public dashboards + +Put a reverse proxy with authentication in front (Caddy + basic auth, Cloudflare Access, or Tailscale). Don't change the port bindings to `0.0.0.0`. + +## Reporting issues + +Open a private security advisory on the GitHub repo. diff --git a/docs/subscriptions.md b/docs/subscriptions.md new file mode 100644 index 0000000..34118d6 --- /dev/null +++ b/docs/subscriptions.md @@ -0,0 +1,51 @@ +# Connect your AI subscriptions + +fleetkit never asks for an API key. Agents sign in to your subscriptions the same way the official apps do, so you pay your normal monthly plan and nothing per token. + +List the ones you have in `fleet.yaml`: + +```yaml +subscriptions: [claude, chatgpt] +``` + +## Claude (Pro or Max) + +```bash +./fleet login claude +``` + +1. A link appears. Open it on any device and approve. +2. Paste the code it shows back into the terminal. +3. Claude prints a long token starting with `sk-ant-oat01-`. Paste it when asked. + +The token lasts a year and is stored in the `fleet-secrets` volume. OpenClaw agents run Claude through the official `claude` CLI, so they use your plan's limits. + +Hermes agents can use Claude too, but Anthropic only allows third-party apps on **Max with extra usage** turned on. On Pro, keep Hermes agents on ChatGPT. + +## ChatGPT (Plus or Pro) + +```bash +./fleet login chatgpt +``` + +You'll see a short code and a link. Open the link, sign in to ChatGPT, enter the code. This runs once for OpenClaw, then once per Hermes agent (each Hermes agent keeps its own login). + +OpenClaw agents run ChatGPT models through Codex, the same engine as the Codex app. + +## Which agent uses which + +| Agent | First choice | Falls back to | +| --- | --- | --- | +| builder | ChatGPT | Claude | +| other OpenClaw agents | Claude | ChatGPT | +| Hermes agents | ChatGPT | Claude (Max only) | + +If you only have one subscription, every agent uses it. To pin a model, set `model:` on an agent in `fleet.yaml`, e.g. `model: anthropic/claude-opus-4-8`. + +## session-warden + +The warden's nightly reflection and weekly review use Claude. With ChatGPT only, the warden still rotates sessions and guards rate limits, but those Claude jobs are skipped. + +## Re-logging in + +Logins expire rarely. If an agent replies with an auth error, run the same `./fleet login` command again. To switch accounts: `./fleet openclaw models auth login --provider openai --device-code --force`. diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..152249a --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,42 @@ +# Upgrading and backups + +## Update + +```bash +./fleet backup +./fleet update +``` + +`update` pulls the latest fleetkit, pulls new images and restarts. Your `fleet.yaml`, `.env`, logins, sessions and memory are kept. + +To stay on a version, set `FLEETKIT_VERSION=0.1.0` (any release tag) in `.env`. To move, change it and run `./fleet up`. + +## Change agents + +Edit `fleet.yaml` and run `./fleet up`. New agents get a starter persona. Existing agents keep theirs. Removing an agent from `fleet.yaml` stops routing messages to it but keeps its files. + +## Backup + +```bash +./fleet backup +``` + +This writes `backups/fleet-