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
44 changes: 44 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
@@ -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
60 changes: 60 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
49 changes: 49 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -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 }}
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ fleet.yaml
backups/
*.log
.DS_Store
__pycache__/
80 changes: 79 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -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 <args> OpenClaw CLI inside the fleet
./fleet hermes <id> <args> 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
15 changes: 15 additions & 0 deletions cloud-init.yaml
Original file line number Diff line number Diff line change
@@ -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"
134 changes: 134 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
@@ -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:
Loading
Loading