From f37114f6a4aa97813c7644dd38c4125410f36c6f Mon Sep 17 00:00:00 2001 From: Ani Date: Wed, 7 Oct 2026 11:46:08 +0530 Subject: [PATCH 1/5] feat: fleet and engram images with compose stack Co-authored-by: Cursor --- .gitignore | 1 + docker-compose.yml | 134 ++++++ images/engram/Dockerfile | 38 ++ images/engram/create-dbs.sql | 3 + images/engram/fleet-engram-tokens.sh | 26 ++ images/fleet/Dockerfile | 62 +++ .../fleet/rootfs/opt/fleetkit/bin/fleet-init | 429 ++++++++++++++++++ .../opt/fleetkit/templates/roles/assistant.md | 15 + .../opt/fleetkit/templates/roles/builder.md | 17 + .../opt/fleetkit/templates/roles/custom.md | 9 + .../opt/fleetkit/templates/roles/ops.md | 18 + .../fleetkit/templates/roles/researcher.md | 15 + .../templates/shared/COMMUNICATION.md | 55 +++ .../rootfs/usr/local/bin/fleet-engram-mcp | 12 + .../rootfs/usr/local/bin/fleet-entrypoint | 53 +++ images/fleet/rootfs/usr/local/bin/systemctl | 9 + 16 files changed, 896 insertions(+) create mode 100644 docker-compose.yml create mode 100644 images/engram/Dockerfile create mode 100644 images/engram/create-dbs.sql create mode 100755 images/engram/fleet-engram-tokens.sh create mode 100644 images/fleet/Dockerfile create mode 100755 images/fleet/rootfs/opt/fleetkit/bin/fleet-init create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/roles/assistant.md create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/roles/builder.md create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/roles/custom.md create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/roles/ops.md create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/roles/researcher.md create mode 100644 images/fleet/rootfs/opt/fleetkit/templates/shared/COMMUNICATION.md create mode 100755 images/fleet/rootfs/usr/local/bin/fleet-engram-mcp create mode 100755 images/fleet/rootfs/usr/local/bin/fleet-entrypoint create mode 100755 images/fleet/rootfs/usr/local/bin/systemctl 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/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/images/engram/Dockerfile b/images/engram/Dockerfile new file mode 100644 index 0000000..17421dc --- /dev/null +++ b/images/engram/Dockerfile @@ -0,0 +1,38 @@ +# engram (shared agent memory) + pinned gbrain, built from upstream source. +# Mirrors https://github.com/Ani-HQ/engram/blob/main/Dockerfile without the +# Cloud SQL proxy, plus the fleet token minter. +FROM oven/bun:1-debian + +RUN apt-get update \ + && apt-get install -y --no-install-recommends git ca-certificates python3 \ + && rm -rf /var/lib/apt/lists/* + +# Bump deliberately. Never build from HEAD. +ARG ENGRAM_REPO=https://github.com/Ani-HQ/engram.git +ARG ENGRAM_COMMIT=240c9646c8d81ab08e2b58283e101e1feb251c2d +ARG GBRAIN_REPO=https://github.com/Ani-HQ/gbrain.git +ARG GBRAIN_COMMIT=4922905fb970d7014625a0190136fbfc8a4f36b0 + +RUN git clone ${ENGRAM_REPO} /app \ + && git -C /app checkout ${ENGRAM_COMMIT} \ + && rm -rf /app/.git + +RUN git clone ${GBRAIN_REPO} /opt/gbrain \ + && git -C /opt/gbrain checkout ${GBRAIN_COMMIT} \ + && python3 /app/deploy/patch-gbrain.py /opt/gbrain/src/core/migrate.ts \ + && cd /opt/gbrain && bun install --frozen-lockfile \ + && printf '#!/bin/sh\nexec bun /opt/gbrain/src/cli.ts "$@"\n' > /usr/local/bin/gbrain \ + && chmod +x /usr/local/bin/gbrain +ENV GBRAIN_BIN=/usr/local/bin/gbrain + +WORKDIR /app +RUN bun install \ + && rm -f .env.local \ + && chmod +x deploy/entrypoint.sh + +COPY fleet-engram-tokens.sh /usr/local/bin/fleet-engram-tokens + +ENV GBRAIN_HOMES_DIR=/gbrain-homes +ENV PORT=8080 +EXPOSE 8080 +CMD ["/app/deploy/entrypoint.sh"] diff --git a/images/engram/create-dbs.sql b/images/engram/create-dbs.sql new file mode 100644 index 0000000..b3f172a --- /dev/null +++ b/images/engram/create-dbs.sql @@ -0,0 +1,3 @@ +-- Shared brain database + gateway database for engram (from Ani-HQ/engram deploy/create-dbs.sql). +CREATE DATABASE brain_shared; +CREATE DATABASE engram_gateway; diff --git a/images/engram/fleet-engram-tokens.sh b/images/engram/fleet-engram-tokens.sh new file mode 100755 index 0000000..feeb8f8 --- /dev/null +++ b/images/engram/fleet-engram-tokens.sh @@ -0,0 +1,26 @@ +#!/bin/sh +# Mint one engram token per fleet client, once. Tokens land in the shared +# fleet-secrets volume, readable only by the fleet containers' uid (1000). +# If a token file goes missing, the old token is revoked and a new one issued. +set -eu + +out=/run/fleet-secrets/engram +mkdir -p "$out" +chmod 700 "$out" + +for client in openclaw hermes warden; do + file="$out/$client.token" + [ -s "$file" ] && continue + name="fleet-$client" + bun cli/engram-admin.ts token revoke --name "$name" >/dev/null 2>&1 || true + token=$(bun cli/engram-admin.ts token issue --name "$name" | tail -n 1) + case "$token" in + eng_*) ;; + *) echo "engram-tokens: could not mint a token for $client" >&2; exit 1 ;; + esac + umask 077 + printf '%s\n' "$token" > "$file" + echo "engram-tokens: issued $name" +done + +chown -R 1000:1000 "$out" diff --git a/images/fleet/Dockerfile b/images/fleet/Dockerfile new file mode 100644 index 0000000..acc650f --- /dev/null +++ b/images/fleet/Dockerfile @@ -0,0 +1,62 @@ +# fleetkit fleet image: OpenClaw gateway + session-warden + fleet board. +# Hermes runs beside it from the official nousresearch/hermes-agent image. +ARG OPENCLAW_VERSION=2026.9.8 +FROM ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION} + +ARG TARGETARCH +ARG CLAUDE_CODE_VERSION=2.1.235 +ARG ENGRAM_MCP_VERSION=0.2.0 +ARG SESSION_WARDEN_REPO=https://github.com/Ani-HQ/session-warden.git +ARG SESSION_WARDEN_COMMIT=1f3c266f253119f8d8418f0d821a2a768834b3d0 +ARG SUPERCRONIC_VERSION=v0.2.49 +ARG SUPERCRONIC_SHA256_amd64=a53ae236602c7338aba3fbaff40bda6300eae3b9fedb8261eb06cfe3724430c1 +ARG SUPERCRONIC_SHA256_arm64=02aa0cb229ba09050cba6638059dadb9eedc2276632ea43d6a57a2f8c1629dd5 + +USER root + +RUN apt-get update \ + && apt-get install -y --no-install-recommends jq python3-yaml sqlite3 procps \ + && rm -rf /var/lib/apt/lists/* + +RUN set -eu; \ + sha="$(eval echo "\$SUPERCRONIC_SHA256_${TARGETARCH}")"; \ + curl -fsSL -o /usr/local/bin/supercronic \ + "https://github.com/aptible/supercronic/releases/download/${SUPERCRONIC_VERSION}/supercronic-linux-${TARGETARCH}"; \ + echo "${sha} /usr/local/bin/supercronic" | sha256sum -c -; \ + chmod +x /usr/local/bin/supercronic + +# Claude Code: the `claude-cli` runtime for Claude Pro/Max subscriptions, and +# the summarizer session-warden uses. engram-mcp: stdio bridge to engram. +RUN npm install -g --no-audit --no-fund \ + "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \ + "@ani-hq/engram-mcp@${ENGRAM_MCP_VERSION}" \ + && npm cache clean --force + +RUN git clone "${SESSION_WARDEN_REPO}" /opt/session-warden \ + && git -C /opt/session-warden checkout "${SESSION_WARDEN_COMMIT}" \ + && rm -rf /opt/session-warden/.git \ + && mv /opt/session-warden/config /opt/session-warden/config.dist \ + && mkdir -p /opt/session-warden/state \ + && ln -s state/config /opt/session-warden/config + +COPY rootfs/ / + +# session-warden and the fleet board expect a host-style home layout: +# ~/session-warden, ~/.npm-global/bin/openclaw, ~/.hermes-. +RUN chmod +x /usr/local/bin/fleet-* /usr/local/bin/systemctl /opt/fleetkit/bin/* \ + && mkdir -p /home/node/.npm-global/bin /home/node/.openclaw /home/node/.hermes \ + /home/node/.claude /run/fleet-secrets /var/lib/fleet-board \ + && ln -sf /usr/local/bin/openclaw /home/node/.npm-global/bin/openclaw \ + && ln -sfn /opt/session-warden /home/node/session-warden \ + && chown -R node:node /home/node /opt/session-warden /run/fleet-secrets \ + /var/lib/fleet-board /opt/fleetkit + +USER node +ENV HOME=/home/node \ + TZ=UTC \ + WARDEN_HOME=/opt/session-warden \ + FLEETKIT_HOME=/opt/fleetkit + +EXPOSE 18789 8090 +ENTRYPOINT ["tini", "-s", "--", "/usr/local/bin/fleet-entrypoint"] +CMD ["gateway"] diff --git a/images/fleet/rootfs/opt/fleetkit/bin/fleet-init b/images/fleet/rootfs/opt/fleetkit/bin/fleet-init new file mode 100755 index 0000000..535d1b1 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/bin/fleet-init @@ -0,0 +1,429 @@ +#!/usr/bin/env python3 +"""Render fleet.yaml into OpenClaw, Hermes and session-warden config. + +Runs on every `./fleet up`, before any gateway starts, and is safe to re-run. +fleet.yaml owns agents, models, channel accounts, bindings and the warden +schedule. Files a human is meant to edit (SOUL.md, ROLE.md, HEARTBEAT.md, +anything outside the managed .env block) are written once, then left alone. +""" + +import json +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path + +import yaml + +HOME = Path.home() +OPENCLAW = HOME / ".openclaw" +HERMES = HOME / ".hermes" +SECRETS = Path("/run/fleet-secrets") +FLEETKIT = Path(os.environ.get("FLEETKIT_HOME", "/opt/fleetkit")) +WARDEN = Path(os.environ.get("WARDEN_HOME", "/opt/session-warden")) +FLEET_YAML = Path("/etc/fleetkit/fleet.yaml") + +ROLES = {"ops", "builder", "assistant", "researcher", "custom"} +CHANNELS = {"discord", "telegram", "whatsapp"} + +# Subscription models, and the OpenClaw runtime that bills each to the plan +# instead of an API key. +MODELS = { + "claude": ["anthropic/claude-sonnet-5", "anthropic/claude-opus-4-8"], + "chatgpt": ["openai/gpt-5.6-terra", "openai/gpt-5.6-sol", "openai/gpt-5.6-luna"], +} +RUNTIME = {"anthropic": "claude-cli", "openai": "codex"} +HERMES_PROVIDER = {"anthropic": "anthropic", "openai": "openai-codex"} + +MANAGED_BEGIN = "# >>> fleetkit managed: edit fleet.yaml / .env instead <<<" +MANAGED_END = "# >>> end fleetkit managed <<<" +AGENTS_MARKER = "" + + +def log(msg): + print(f"[fleet-init] {msg}", file=sys.stderr, flush=True) + + +def die(msg): + log(f"error: {msg}") + sys.exit(1) + + +def load_fleet(): + if not FLEET_YAML.is_file(): + die(f"{FLEET_YAML} is missing. Run ./fleet setup on the host.") + fleet = yaml.safe_load(FLEET_YAML.read_text()) or {} + owner = fleet.setdefault("owner", {}) + owner.setdefault("name", "owner") + owner.setdefault("timezone", "UTC") + + subs = fleet.get("subscriptions") or [] + if not subs or set(subs) - set(MODELS): + die("fleet.yaml `subscriptions` must list claude and/or chatgpt") + + seen, whatsapp = set(), {} + for agent in fleet.setdefault("agents", []): + aid = str(agent.get("id", "")) + if not re.fullmatch(r"[a-z][a-z0-9-]{0,31}", aid): + die(f"agent id {aid!r} must be lowercase letters, digits or dashes") + if aid in seen or aid in {"main", "default"}: + die(f"agent id {aid!r} is duplicated or reserved") + seen.add(aid) + agent.setdefault("name", aid.capitalize()) + agent.setdefault("role", "custom") + if agent.get("harness") not in {"openclaw", "hermes"}: + die(f"agent {aid}: harness must be openclaw or hermes") + if agent["role"] not in ROLES: + die(f"agent {aid}: role must be one of {sorted(ROLES)}") + chans = agent.setdefault("channels", []) + if set(chans) - CHANNELS: + die(f"agent {aid}: channels must be from {sorted(CHANNELS)}") + if "whatsapp" in chans and whatsapp.setdefault(agent["harness"], aid) != aid: + die(f"only one {agent['harness']} agent can own WhatsApp") + + fleet.setdefault("defaults", {}) + fleet.setdefault("memory", {}).setdefault("enabled", True) + fleet.setdefault("warden", {}).setdefault("enabled", True) + return fleet + + +def env_name(prefix, aid): + return f"{prefix}_{aid.upper().replace('-', '_')}" + + +def model_pool(subs, order): + return [m for sub in order if sub in subs for m in MODELS[sub]] + + +def model_chain(agent, subs, order): + pool = model_pool(subs, order) + primary = agent.get("model") or pool[0] + return primary, [m for m in pool if m != primary] + + +def read_secret(name): + path = SECRETS / name + return path.read_text().strip() if path.is_file() else "" + + +def write_once(path, text): + if not path.exists(): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + +def template(*parts): + return (FLEETKIT / "templates" / Path(*parts)).read_text() + + +# ── OpenClaw ──────────────────────────────────────────────────────────────── + +def openclaw(*args, check=True): + res = subprocess.run(["openclaw", *args], capture_output=True, text=True) + if check and res.returncode != 0: + die(f"openclaw {' '.join(args[:3])} failed:\n{res.stdout}{res.stderr}") + return res + + +def env_ref(name): + return {"source": "env", "provider": "default", "id": name} + + +def channel_account(chan, aid): + """Per-agent bot account for OpenClaw, or None if its token is missing.""" + if chan == "whatsapp": + number = os.environ.get("OWNER_WHATSAPP_NUMBER", "").lstrip("+") + account, owner = {}, (f"+{number}" if number else "") + else: + prefix, field, owner_var = { + "discord": ("DISCORD_TOKEN", "token", "OWNER_DISCORD_ID"), + "telegram": ("TELEGRAM_TOKEN", "botToken", "OWNER_TELEGRAM_ID"), + }[chan] + token = env_name(prefix, aid) + if not os.environ.get(token): + log(f"skip {chan} for {aid}: {token} is empty in .env") + return None + account, owner = {field: env_ref(token)}, os.environ.get(owner_var, "") + if owner: + account.update(dmPolicy="allowlist", allowFrom=[owner]) + else: + account["dmPolicy"] = "pairing" + return account + + +def seed_workspace(workspace, agent): + role = template("roles", f"{agent['role']}.md") + write_once(workspace / "ROLE.md", role) + hb = workspace / "HEARTBEAT.md" + if not hb.exists() or "Keep this file empty" in hb.read_text(): + hb.write_text("# HEARTBEAT.md\n" + role.split("## Heartbeat checklist", 1)[-1]) + agents_md = workspace / "AGENTS.md" + text = agents_md.read_text() if agents_md.exists() else "" + if AGENTS_MARKER in text: + return + agents_md.write_text(text.rstrip() + f""" + +{AGENTS_MARKER} +## Fleet + +You are **{agent['name']}**, one agent in a fleet. At session start, also read: + +- `ROLE.md`: what you own in this fleet +- `~/.openclaw/shared/COMMUNICATION.md`: how to write to humans (every message) + +If an `engram` tool is available, it is the fleet's shared memory: `recall` +before substantial work, `remember` decisions and hand-offs. +""") + + +def setup_openclaw(fleet): + agents = [a for a in fleet["agents"] if a["harness"] == "openclaw"] + subs, tz, defaults = fleet["subscriptions"], fleet["owner"]["timezone"], fleet["defaults"] + + if not (OPENCLAW / "openclaw.json").is_file(): + log("first boot: onboarding OpenClaw") + openclaw("onboard", "--non-interactive", "--accept-risk", "--mode", "local", + "--auth-choice", "skip", "--gateway-auth", "token", + "--gateway-token-ref-env", "OPENCLAW_GATEWAY_TOKEN", "--gateway-bind", "lan", + "--skip-health", "--skip-channels", "--skip-daemon", "--skip-search", + "--skip-skills", "--skip-ui", "--skip-hooks") + + config = json.loads((OPENCLAW / "openclaw.json").read_text()) + existing = config.get("agents", {}).get("entries", {}) + for agent in agents: + workspace = OPENCLAW / "agents" / agent["id"] + if agent["id"] not in existing: + log(f"adding OpenClaw agent {agent['id']}") + openclaw("agents", "add", agent["id"], "--workspace", str(workspace), "--non-interactive") + seed_workspace(workspace, agent) + write_once(OPENCLAW / "shared" / "COMMUNICATION.md", template("shared", "COMMUNICATION.md")) + + primary, fallbacks = model_chain({}, subs, ["claude", "chatgpt"]) + ops = [ + {"path": "gateway.bind", "value": "lan"}, + {"path": "gateway.controlUi.allowedOrigins", + "value": ["http://localhost:18789", "http://127.0.0.1:18789"]}, + {"path": "agents.defaults.models", + "value": {m: {"agentRuntime": {"id": RUNTIME[m.split("/")[0]]}} + for m in model_pool(subs, ["claude", "chatgpt"])}}, + {"path": "agents.defaults.model", "value": {"primary": primary, "fallbacks": fallbacks}}, + ] + + bindings, enabled = [], set() + for agent in agents: + aid = agent["id"] + order = ["chatgpt", "claude"] if agent["role"] == "builder" else ["claude", "chatgpt"] + primary, fallbacks = model_chain(agent, subs, order) + heartbeat = {"every": str(defaults.get("heartbeat", "1h"))} + if defaults.get("active_hours"): + hours = defaults["active_hours"] + heartbeat["activeHours"] = {"start": hours["start"], "end": hours["end"], "timezone": tz} + ops += [ + {"path": f"agents.entries.{aid}.name", "value": agent["name"]}, + {"path": f"agents.entries.{aid}.identity.name", "value": agent["name"]}, + {"path": f"agents.entries.{aid}.model", "value": {"primary": primary, "fallbacks": fallbacks}}, + {"path": f"agents.entries.{aid}.heartbeat", "value": heartbeat}, + ] + for chan in agent["channels"]: + account = channel_account(chan, aid) + if account is None: + continue + enabled.add(chan) + ops += [{"path": f"channels.{chan}.accounts.{aid}.{k}", "value": v} for k, v in account.items()] + bindings.append({"type": "route", "agentId": aid, "match": {"channel": chan, "accountId": aid}}) + + ops += [{"path": f"channels.{chan}.enabled", "value": True} for chan in sorted(enabled)] + if "discord" in enabled: + ops.append({"path": "channels.discord.groupPolicy", "value": "open"}) + ops.append({"path": "bindings", "value": bindings}) + # Built-in semantic search needs an embeddings API key; subscriptions-only fleets use engram. + ops.append({"path": "memory.search.enabled", "value": False}) + + if fleet["memory"]["enabled"]: + ops.append({"path": "mcp.servers.engram", "value": {"command": "fleet-engram-mcp"}}) + elif "engram" in config.get("mcp", {}).get("servers", {}): + openclaw("config", "unset", "mcp.servers.engram", check=False) + + if "whatsapp" in enabled and not (OPENCLAW / "extensions" / "whatsapp").exists(): + log("installing the OpenClaw WhatsApp plugin") + openclaw("plugins", "install", "@openclaw/whatsapp", check=False) + + openclaw("config", "set", "--batch-json", json.dumps(ops)) + openclaw("config", "validate") + log(f"OpenClaw: {len(agents)} agent(s), {len(bindings)} channel binding(s)") + + +# ── Hermes ────────────────────────────────────────────────────────────────── + +def hermes_agents(fleet): + return [a for a in fleet["agents"] if a["harness"] == "hermes"] + + +def hermes_home(index, agent): + """The first Hermes agent is the default profile; the rest are named profiles.""" + return HERMES if index == 0 else HERMES / "profiles" / agent["id"] + + +def hermes_model(model): + provider, _, name = model.partition("/") + return HERMES_PROVIDER[provider], name + + +def write_managed_env(path, values): + """Replace only the fleetkit block; keep anything a human added.""" + text = path.read_text() if path.exists() else "" + block = re.compile(re.escape(MANAGED_BEGIN) + r".*?" + re.escape(MANAGED_END) + r"\n?", re.S) + body = "\n".join(f"{k}={v}" for k, v in values.items() if v) + text = f"{block.sub('', text).rstrip()}\n\n{MANAGED_BEGIN}\n{body}\n{MANAGED_END}\n".lstrip() + path.write_text(text) + path.chmod(0o600) + + +def setup_hermes(fleet): + subs = fleet["subscriptions"] + engram_token = read_secret("engram/hermes.token") if fleet["memory"]["enabled"] else "" + claude_token = read_secret("claude-oauth-token") + + for index, agent in enumerate(hermes_agents(fleet)): + aid, home = agent["id"], hermes_home(index, agent) + home.mkdir(parents=True, exist_ok=True) + + # Hermes bills Claude only to Max plans with extra usage credits, so + # it leads with ChatGPT when both subscriptions are connected. + primary, fallbacks = model_chain(agent, subs, ["chatgpt", "claude"]) + provider, name = hermes_model(primary) + cfg_path = home / "config.yaml" + cfg = (yaml.safe_load(cfg_path.read_text()) if cfg_path.exists() else None) or {} + cfg["model"] = {**(cfg.get("model") or {}), "default": name, "provider": provider} + cfg["fallback_providers"] = [dict(zip(("provider", "model"), hermes_model(m))) + for m in fallbacks[:2]] + cfg["timezone"] = fleet["owner"]["timezone"] + servers = cfg.get("mcp_servers") or {} + if engram_token: + servers["engram"] = {"url": "http://engram:8080/mcp", + "headers": {"Authorization": "Bearer ${ENGRAM_TOKEN}"}} + else: + servers.pop("engram", None) + cfg["mcp_servers"] = servers + if index == 0: + cfg.setdefault("gateway", {})["multiplex_profiles"] = True + cfg_path.write_text(yaml.safe_dump(cfg, sort_keys=False)) + + write_once(home / "SOUL.md", f"# {agent['name']}\n\n{template('roles', agent['role'] + '.md')}\n" + f"{template('shared', 'COMMUNICATION.md')}") + + env, chans = {}, agent["channels"] + for chan, prefix, owner_var in [("telegram", "TELEGRAM", "OWNER_TELEGRAM_ID"), + ("discord", "DISCORD", "OWNER_DISCORD_ID")]: + if chan not in chans: + continue + token = os.environ.get(env_name(f"{prefix}_TOKEN", aid), "") + if not token: + log(f"skip {chan} for {aid}: {env_name(prefix + '_TOKEN', aid)} is empty in .env") + continue + env[f"{prefix}_BOT_TOKEN"] = token + env[f"{prefix}_ALLOWED_USERS"] = os.environ.get(owner_var, "") + if "whatsapp" in chans: + env.update(WHATSAPP_ENABLED="true", WHATSAPP_MODE="bot", + WHATSAPP_ALLOWED_USERS=os.environ.get("OWNER_WHATSAPP_NUMBER", "").lstrip("+")) + env["ENGRAM_TOKEN"] = engram_token + if "claude" in subs: + env["CLAUDE_CODE_OAUTH_TOKEN"] = claude_token + write_managed_env(home / ".env", env) + + log(f"Hermes: {len(hermes_agents(fleet))} profile(s)") + + +def link_hermes_homes(fleet): + """session-warden looks for Hermes agents at ~/.hermes-.""" + for index, agent in enumerate(hermes_agents(fleet)): + link = HOME / f".hermes-{agent['id']}" + if link.is_symlink() or link.exists(): + link.unlink() + link.symlink_to(hermes_home(index, agent)) + + +# ── session-warden ────────────────────────────────────────────────────────── + +CRON = """\ +# Generated by fleet-init from fleet.yaml. Times are in {tz}. +*/2 * * * * {w}/bin/rate-guard.sh --once +*/30 * * * * {w}/bin/snapshot.sh +30 3 * * * {w}/bin/dream-cycle.sh +10 4 * * * {w}/bin/reflect.sh +30 6 * * 6 {w}/bin/fleet-review.sh +0 5 * * 0 {w}/bin/harvest-skills.sh +0 7 1 * * {w}/bin/eval-memory.sh +*/10 * * * * FLEET_OUT=/var/lib/fleet-board {w}/contrib/fleet-live/generate.sh +""" + + +def setup_warden(fleet): + crontab = OPENCLAW / "fleetkit" / "crontab" + crontab.parent.mkdir(parents=True, exist_ok=True) + if not fleet["warden"]["enabled"]: + crontab.unlink(missing_ok=True) + log("session-warden: off") + return + + config = WARDEN / "state" / "config" + config.mkdir(parents=True, exist_ok=True) + for src in (WARDEN / "config.dist").iterdir(): + dest = config / src.name.removesuffix(".example") + if dest.exists(): + continue + (shutil.copytree if src.is_dir() else shutil.copy)(src, dest) + + thresholds = config / "thresholds.env" + if thresholds.exists(): + text = thresholds.read_text() + for key in ("WARDEN_TELEGRAM_BOT_TOKEN", "WARDEN_TELEGRAM_CHAT_ID"): + text = re.sub(rf"^{key}=$", f"{key}=${{{key}:-}}", text, flags=re.M) + thresholds.write_text(text) + + rows = ["# Generated by fleet-init from fleet.yaml", + "# agent\tteam\tchannel\trole\tboard\ttitle\tblurb"] + for agent in fleet["agents"]: + if agent["harness"] == "openclaw": + chan = (agent["channels"] or ["internal"])[0] + rows.append("\t".join([agent["id"], "fleet", chan, agent["role"], "1", + agent["name"], f"{agent['role']} agent"])) + (config / "fleet-roster.tsv").write_text("\n".join(rows) + "\n") + + cron = CRON.format(tz=fleet["owner"]["timezone"], w=WARDEN) + if hermes_agents(fleet): + cron += f"0 6 * * 6 {WARDEN}/bin/scorecard.sh\n" + crontab.write_text(cron) + log("session-warden: schedule written") + + +# ── main ──────────────────────────────────────────────────────────────────── + +def write_fleet_env(fleet): + values = { + "FLEET_TZ": fleet["owner"]["timezone"], + "WARDEN_SCORECARD_AGENTS": " ".join(a["id"] for a in hermes_agents(fleet)), + "CLAUDE_CODE_OAUTH_TOKEN": read_secret("claude-oauth-token"), + } + path = SECRETS / "fleet.env" + path.write_text("".join(f"{k}={json.dumps(v)}\n" for k, v in values.items() if v)) + path.chmod(0o600) + + +def main(): + fleet = load_fleet() + if "--links-only" in sys.argv: + link_hermes_homes(fleet) + return + write_fleet_env(fleet) + setup_openclaw(fleet) + setup_hermes(fleet) + link_hermes_homes(fleet) + setup_warden(fleet) + log("done") + + +if __name__ == "__main__": + main() diff --git a/images/fleet/rootfs/opt/fleetkit/templates/roles/assistant.md b/images/fleet/rootfs/opt/fleetkit/templates/roles/assistant.md new file mode 100644 index 0000000..8e215a5 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/roles/assistant.md @@ -0,0 +1,15 @@ +## Your role: personal assistant + +You are the owner's day-to-day assistant on chat. You answer questions, +draft messages, remember things, and set reminders. + +- Lead with the answer. Yes or no first, then the reason. +- When the owner says "remember this", write it to memory right away. +- Draft, don't send: anything addressed to another person goes back to the + owner for approval first. +- Respect quiet hours. Outside them, only interrupt for something urgent. + +## Heartbeat checklist + +- Any reminder that is now due? Send it. +- Otherwise reply `HEARTBEAT_OK`. diff --git a/images/fleet/rootfs/opt/fleetkit/templates/roles/builder.md b/images/fleet/rootfs/opt/fleetkit/templates/roles/builder.md new file mode 100644 index 0000000..04a99b8 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/roles/builder.md @@ -0,0 +1,17 @@ +## Your role: builder + +You write and ship code. You own technical work end to end: understand the +ask, make the change, test it, and report what shipped. + +- Work in a git branch, never directly on `main`. Open a pull request when + the change is ready and say what you tested. +- Prefer small, reviewable changes over large rewrites. +- Run the project's tests and linters before calling something done. If you + could not test it, say so plainly. +- Ask before deleting data, rewriting history, or touching production. + +## Heartbeat checklist + +- Any pull request of yours with new review comments or failing checks? + Fix it or report the blocker. +- Otherwise reply `HEARTBEAT_OK`. diff --git a/images/fleet/rootfs/opt/fleetkit/templates/roles/custom.md b/images/fleet/rootfs/opt/fleetkit/templates/roles/custom.md new file mode 100644 index 0000000..176e184 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/roles/custom.md @@ -0,0 +1,9 @@ +## Your role + +_Describe what this agent owns, what it should never do, and what "done" +looks like. Edit this file in the agent's workspace; the fleet will not +overwrite it._ + +## Heartbeat checklist + +- Otherwise reply `HEARTBEAT_OK`. diff --git a/images/fleet/rootfs/opt/fleetkit/templates/roles/ops.md b/images/fleet/rootfs/opt/fleetkit/templates/roles/ops.md new file mode 100644 index 0000000..d0145a0 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/roles/ops.md @@ -0,0 +1,18 @@ +## Your role: operations + +You keep the owner's work moving. You track open loops, chase what is stuck, +and make sure nothing important is forgotten. + +- Keep a running list of open tasks in `memory/open-loops.md`. Close items + when they are done; don't let the list rot. +- When asked for a standup or summary, use the done / blocked / next shape. +- Coordinate with the other agents in the fleet instead of doing their work. + Hand coding to the builder, research to the researcher. +- Anything that leaves the machine (emails, posts, messages to people outside + the team) needs the owner's explicit go-ahead. + +## Heartbeat checklist + +- Any open loop past its due date? Nudge once, then escalate to the owner. +- Anything the owner asked for that is now done? Tell them. +- Otherwise reply `HEARTBEAT_OK`. diff --git a/images/fleet/rootfs/opt/fleetkit/templates/roles/researcher.md b/images/fleet/rootfs/opt/fleetkit/templates/roles/researcher.md new file mode 100644 index 0000000..6bf15d5 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/roles/researcher.md @@ -0,0 +1,15 @@ +## Your role: researcher + +You find things out. You turn a vague question into a short, sourced answer +the owner can act on. + +- Start with the answer in two or three lines, then the evidence. +- Link every claim that matters to its source. Say when sources disagree or + when you are unsure. +- Save durable findings to memory so other agents can reuse them. +- Don't pad. If the honest answer is "not enough data", say that. + +## Heartbeat checklist + +- Any research the owner is waiting on that you can finish now? Finish it. +- Otherwise reply `HEARTBEAT_OK`. diff --git a/images/fleet/rootfs/opt/fleetkit/templates/shared/COMMUNICATION.md b/images/fleet/rootfs/opt/fleetkit/templates/shared/COMMUNICATION.md new file mode 100644 index 0000000..ea773c6 --- /dev/null +++ b/images/fleet/rootfs/opt/fleetkit/templates/shared/COMMUNICATION.md @@ -0,0 +1,55 @@ +# COMMUNICATION.md: how every agent in this fleet talks to humans + +People ignore noisy agents. Your job is the opposite: +**fewer messages, each one worth reading.** + +This applies to every agent in the fleet. Chat channels are not a diary. + +## When to speak + +Send a visible message only when at least one is true: + +1. A human must **decide** or **unblock** something +2. Something they asked for is **done** and ready for them +3. There is a **new** risk, failure or deadline they don't already know about + +Otherwise stay quiet, write it to memory, or reply `HEARTBEAT_OK`. + +Do **not** send: + +- recaps of blockers you already reported +- "standing by", "no updates", "still waiting" +- process narration ("I checked X, then Y, then Z") +- status essays that pack several topics into one paragraph + +If the reader would shrug and scroll past, don't send it. + +## How to write + +Rewrite every chat message so a busy person can scan it in three seconds. + +1. No walls of text. +2. Short labeled sections and bullets, with a blank line between sections. +3. Plain language. A smart teammate, not a status API. +4. One idea per line. +5. Keep the main message to about 8 short lines. Put details in a thread. +6. Discord and WhatsApp: no markdown tables. On Discord, wrap links in `<>`. + +Default shape (leave out empty sections): + +**done** +- ... + +**blocked** (needs you) +- ... + +**next** +- ... + +Every message should make the reader's next action obvious. If there is none, +ask whether the message should exist at all. + +## Long tasks + +Stay in the turn until the work is finished or you are blocked. Short one-line +progress notes while working are fine; don't expand them into reports. diff --git a/images/fleet/rootfs/usr/local/bin/fleet-engram-mcp b/images/fleet/rootfs/usr/local/bin/fleet-engram-mcp new file mode 100755 index 0000000..02b1b26 --- /dev/null +++ b/images/fleet/rootfs/usr/local/bin/fleet-engram-mcp @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +# stdio MCP bridge to the fleet's engram server, for OpenClaw agents. +set -euo pipefail +token_file=/run/fleet-secrets/engram/openclaw.token +if [ ! -s "$token_file" ]; then + echo "fleet-engram-mcp: no engram token yet (is memory enabled?)" >&2 + exit 1 +fi +export ENGRAM_HOST="${ENGRAM_HOST:-http://engram:8080}" +ENGRAM_TOKEN="$(cat "$token_file")" +export ENGRAM_TOKEN +exec engram-mcp "$@" diff --git a/images/fleet/rootfs/usr/local/bin/fleet-entrypoint b/images/fleet/rootfs/usr/local/bin/fleet-entrypoint new file mode 100755 index 0000000..05e461a --- /dev/null +++ b/images/fleet/rootfs/usr/local/bin/fleet-entrypoint @@ -0,0 +1,53 @@ +#!/usr/bin/env bash +# fleet-entrypoint: one image, three jobs. +# init render fleet.yaml into OpenClaw + Hermes config, then exit +# gateway run OpenClaw, with session-warden cron and the fleet board beside it +# pass through (e.g. `openclaw doctor`, `bash`) +set -euo pipefail + +export TZ="${FLEET_TZ:-${TZ:-UTC}}" +[ -f /run/fleet-secrets/fleet.env ] && set -a && . /run/fleet-secrets/fleet.env && set +a + +log() { printf '[fleet] %s\n' "$*" >&2; } + +# Restart a background helper forever; it must never take the gateway down. +supervise() { + local name="$1"; shift + ( + while true; do + "$@" || log "$name exited ($?), restarting in 10s" + sleep 10 + done + ) & +} + +case "${1:-gateway}" in + init) + # Runs as root once per boot: the Hermes image can seed the shared volume + # with its own uid before we get here, so hand every volume to node first. + if [ "$(id -u)" = 0 ]; then + chown -R node:node /home/node/.openclaw /home/node/.hermes /home/node/.claude \ + /opt/session-warden/state /run/fleet-secrets + exec setpriv --reuid=node --regid=node --init-groups python3 /opt/fleetkit/bin/fleet-init + fi + exec python3 /opt/fleetkit/bin/fleet-init + ;; + + gateway) + python3 /opt/fleetkit/bin/fleet-init --links-only || log "could not link Hermes homes" + [ -f /var/lib/fleet-board/index.html ] || + printf '

Fleet board: first snapshot in about 10 minutes.

\n' > /var/lib/fleet-board/index.html + crontab="$HOME/.openclaw/fleetkit/crontab" + if [ -s "$crontab" ]; then + supervise warden supercronic -quiet "$crontab" + log "session-warden schedule loaded" + fi + supervise board python3 -m http.server 8090 --bind 0.0.0.0 \ + --directory /var/lib/fleet-board + exec node /app/docker-entrypoint.mjs node /app/openclaw.mjs gateway + ;; + + *) + exec "$@" + ;; +esac diff --git a/images/fleet/rootfs/usr/local/bin/systemctl b/images/fleet/rootfs/usr/local/bin/systemctl new file mode 100755 index 0000000..9b1b677 --- /dev/null +++ b/images/fleet/rootfs/usr/local/bin/systemctl @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +# Containers have no systemd. session-warden asks systemd to restart gateways +# after it edits their config; OpenClaw and Hermes both reload config on their +# own, so log the request and report success. +printf '[fleet] systemctl %s: no systemd in container, config hot-reload applies\n' "$*" >&2 +case " $* " in + *" is-active "*) echo active ;; +esac +exit 0 From 970235940cd32cb185a10b313f9ae555b0e643a8 Mon Sep 17 00:00:00 2001 From: Ani Date: Wed, 7 Oct 2026 11:46:08 +0530 Subject: [PATCH 2/5] feat: fleet CLI with setup wizard and subscription logins Co-authored-by: Cursor --- .env.example | 44 +++++++ fleet | 319 +++++++++++++++++++++++++++++++++++++++++++++ fleet.example.yaml | 64 +++++++++ 3 files changed, 427 insertions(+) create mode 100644 .env.example create mode 100755 fleet create mode 100644 fleet.example.yaml 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/fleet b/fleet new file mode 100755 index 0000000..4fb8d53 --- /dev/null +++ b/fleet @@ -0,0 +1,319 @@ +#!/usr/bin/env bash +# fleet: run your AI agent fleet. `./fleet help` lists commands. +set -euo pipefail + +cd "$(dirname "$0")" + +bold() { printf '\033[1m%s\033[0m\n' "$*"; } +info() { printf ' %s\n' "$*"; } +warn() { printf ' ! %s\n' "$*" >&2; } +die() { printf 'fleet: %s\n' "$*" >&2; exit 1; } + +compose() { docker compose "$@"; } + +need_setup() { + [ -f .env ] && [ -f fleet.yaml ] || die "run ./fleet setup first" +} + +memory_enabled() { + awk '/^memory:/{m=1;next} /^[^ #]/{m=0} m && /enabled:/{print $2; exit}' fleet.yaml | + grep -qv false +} + +export_profiles() { + if memory_enabled; then export COMPOSE_PROFILES=memory; else export COMPOSE_PROFILES=; fi +} + +# Ask fleet.yaml a question with the fleet image's own parser. +fleet_query() { + compose run --rm --no-deps -T --entrypoint python3 openclaw -c " +import yaml, sys +f = yaml.safe_load(open('/etc/fleetkit/fleet.yaml')) +agents = f.get('agents') or [] +q = sys.argv[1] +if q == 'hermes': + print(' '.join(a['id'] for a in agents if a.get('harness') == 'hermes')) +elif q.startswith('harness:'): + aid = q.split(':', 1)[1] + print(next((a.get('harness', '') for a in agents if a['id'] == aid), '')) +" "$1" +} + +# `hermes` CLI for one agent: the first Hermes agent is the default profile. +hermes_exec() { + local aid="$1"; shift + local first; first=$(fleet_query hermes | awk '{print $1}') + if [ "$aid" = "$first" ]; then + compose exec -it -u hermes hermes hermes "$@" + else + compose exec -it -u hermes hermes hermes -p "$aid" "$@" + fi +} + +ask() { + local prompt="$1" default="${2:-}" answer + if [ -n "$default" ]; then read -rp " $prompt [$default]: " answer; else read -rp " $prompt: " answer; fi + printf '%s' "${answer:-$default}" +} + +ask_secret() { + local answer + read -rsp " $1: " answer; echo >&2 + printf '%s' "$answer" +} + +set_env() { + local key="$1" value="$2" + if grep -q "^${key}=" .env; then + python3 - "$key" "$value" <<'PY' +import sys, re, pathlib +key, value = sys.argv[1], sys.argv[2] +p = pathlib.Path(".env") +p.write_text(re.sub(rf"^{re.escape(key)}=.*$", lambda _: f"{key}={value}", p.read_text(), flags=re.M)) +PY + else + printf '%s=%s\n' "$key" "$value" >> .env + fi +} + +cmd_setup() { + command -v docker >/dev/null || die "Docker is not installed. On a fresh server, use install.sh." + bold "fleet setup" + echo " Answers go to fleet.yaml (agents) and .env (secrets). Re-run any time." + echo + + [ -f .env ] || cp .env.example .env + chmod 600 .env + for key in OPENCLAW_GATEWAY_TOKEN HERMES_DASHBOARD_PASSWORD POSTGRES_PASSWORD; do + grep -q "^${key}=." .env || set_env "$key" "$(openssl rand -hex 24)" + done + + if [ -f fleet.yaml ] && [ "$(ask 'fleet.yaml exists. Keep it?' Y)" != "n" ]; then + info "keeping fleet.yaml" + else + local name tz subs claude chatgpt + name=$(ask "Your name" "$(id -un)") + tz=$(ask "Your timezone (IANA, e.g. Europe/London, Asia/Kolkata)" "UTC") + echo " Which AI subscriptions do you have? (no API keys needed)" + claude=$(ask " Claude Pro or Max? y/n" y) + chatgpt=$(ask " ChatGPT Plus or Pro? y/n" y) + subs="" + [ "$claude" = y ] && subs="claude" + [ "$chatgpt" = y ] && subs="${subs:+$subs, }chatgpt" + [ -n "$subs" ] || die "you need at least one subscription" + + echo " Starter agents: ops + builder (OpenClaw), assistant (Hermes)." + local ops_ch builder_ch asst_ch + ops_ch=$(ask "Ops agent channel (discord/telegram/whatsapp/none)" discord) + builder_ch=$(ask "Builder agent channel (discord/telegram/none)" discord) + asst_ch=$(ask "Assistant agent channel (telegram/discord/whatsapp/none)" telegram) + sed -e "s/^ name: Sam$/ name: ${name}/" \ + -e "s|^ timezone: Europe/London$| timezone: ${tz}|" \ + -e "s/^subscriptions: .*/subscriptions: [${subs}]/" \ + fleet.example.yaml > fleet.yaml + python3 - "$ops_ch" "$builder_ch" "$asst_ch" <<'PY' +import sys, pathlib +chans = [("ops", sys.argv[1]), ("builder", sys.argv[2]), ("assistant", sys.argv[3])] +p = pathlib.Path("fleet.yaml") +lines, current = p.read_text().splitlines(), None +for i, line in enumerate(lines): + if line.strip().startswith("- id: "): + current = line.split(":", 1)[1].strip() + elif line.strip().startswith("channels:") and current: + ch = dict(chans).get(current, "") + lines[i] = line.split("channels:")[0] + f"channels: [{'' if ch in ('', 'none') else ch}]" +p.write_text("\n".join(lines) + "\n") +PY + info "wrote fleet.yaml" + fi + + echo + bold "Chat access" + echo " Agents only answer you in DMs. Leave blank for platforms you don't use." + local v + v=$(ask "Your Discord user ID (Settings → Advanced → Developer Mode, right-click yourself → Copy ID)" "$(grep '^OWNER_DISCORD_ID=' .env | cut -d= -f2-)") + set_env OWNER_DISCORD_ID "$v" + v=$(ask "Your Telegram user ID (message @userinfobot)" "$(grep '^OWNER_TELEGRAM_ID=' .env | cut -d= -f2-)") + set_env OWNER_TELEGRAM_ID "$v" + v=$(ask "Your WhatsApp number, digits with country code" "$(grep '^OWNER_WHATSAPP_NUMBER=' .env | cut -d= -f2-)") + set_env OWNER_WHATSAPP_NUMBER "$v" + + echo + bold "Bot tokens" + echo " One bot per agent. Guides: docs/channels.md. Enter to keep the current value." + python3 - <<'PY' > .fleet-tokens +import re, pathlib +text = pathlib.Path("fleet.yaml").read_text() +for block in re.split(r"\n\s*- id: ", text)[1:]: + aid = block.split("\n", 1)[0].strip() + m = re.search(r"channels:\s*\[(.*?)\]", block) + for ch in [c.strip() for c in (m.group(1) if m else "").split(",") if c.strip()]: + if ch in ("discord", "telegram"): + print(f"{ch.upper()}_TOKEN_{aid.upper().replace('-', '_')}") +PY + while read -r key; do + v=$(ask_secret "$key") + [ -n "$v" ] && set_env "$key" "$v" + done < .fleet-tokens + rm -f .fleet-tokens + + echo + bold "Next" + info "./fleet up start the fleet" + info "./fleet login claude connect your Claude subscription" + info "./fleet login chatgpt connect your ChatGPT subscription" + info "./fleet whatsapp pair WhatsApp (if you chose it)" +} + +cmd_up() { + need_setup + export_profiles + bold "starting the fleet" + if [ "${FLEET_BUILD:-}" = 1 ] || ! compose pull --quiet 2>/dev/null; then + info "building images locally (first time takes a few minutes)" + compose build + fi + compose up -d --remove-orphans + echo + cmd_status +} + +cmd_status() { + need_setup + export_profiles + compose ps --format 'table {{.Service}}\t{{.Status}}' + echo + compose logs --no-log-prefix init 2>/dev/null | grep -E '^\[fleet-init\]' | tail -n 12 || true +} + +cmd_login() { + need_setup + export_profiles + case "${1:-}" in + claude) + bold "Connect your Claude subscription" + echo " 1. Open the link below and approve." + echo " 2. Paste the code back here." + echo " 3. Claude prints a token starting with sk-ant-oat01-. Copy it." + echo + compose exec -it openclaw claude setup-token || true + echo + local token + token=$(ask_secret "Paste the sk-ant-oat01- token") + case "$token" in sk-ant-oat01-*) ;; *) die "that doesn't look like a Claude setup token" ;; esac + printf '%s' "$token" | compose exec -T openclaw sh -c \ + 'umask 077; cat > /run/fleet-secrets/claude-oauth-token' + printf '%s\n' "$token" | compose exec -T openclaw \ + openclaw models auth paste-token --provider anthropic >/dev/null \ + || warn "OpenClaw did not accept the token; agents still use it through the claude CLI" + info "saved. Applying to every agent..." + cmd_up >/dev/null + compose restart openclaw hermes >/dev/null + info "Claude connected." + ;; + chatgpt) + bold "Connect your ChatGPT subscription" + echo " OpenClaw agents first, then each Hermes agent. Each shows a code to enter at the link." + echo + compose exec -it openclaw openclaw models auth login --provider openai --device-code + for aid in $(fleet_query hermes); do + echo; bold "Hermes agent: $aid" + hermes_exec "$aid" auth add openai-codex + done + info "ChatGPT connected." + ;; + *) die "usage: ./fleet login claude|chatgpt" ;; + esac +} + +cmd_whatsapp() { + need_setup + local aid="${1:-}" + [ -n "$aid" ] || die "usage: ./fleet whatsapp " + echo " On your phone: WhatsApp → Settings → Linked devices → Link a device, then scan." + case "$(fleet_query "harness:$aid")" in + openclaw) compose exec -it openclaw openclaw channels login --channel whatsapp --account "$aid" ;; + hermes) hermes_exec "$aid" whatsapp ;; + *) die "no agent called $aid in fleet.yaml" ;; + esac +} + +cmd_ui() { + need_setup + local token host + token=$(grep '^OPENCLAW_GATEWAY_TOKEN=' .env | cut -d= -f2-) + host=$(hostname -I 2>/dev/null | awk '{print $1}') + bold "Dashboards (bound to localhost on the server)" + echo " From your laptop, open a tunnel:" + echo " ssh -L 18789:localhost:18789 -L 9119:localhost:9119 -L 8090:localhost:8090 -L 8080:localhost:8080 @${host:-your-server}" + echo + echo " OpenClaw Control UI http://localhost:18789 token: $token" + echo " Hermes dashboard http://localhost:9119 user: admin password: $(grep '^HERMES_DASHBOARD_PASSWORD=' .env | cut -d= -f2-)" + echo " Fleet board http://localhost:8090" + memory_enabled && echo " Memory (engram) http://localhost:8080" +} + +cmd_update() { + need_setup + git pull --ff-only + cmd_up +} + +cmd_backup() { + need_setup + export_profiles + local stamp out + stamp=$(date -u +%Y%m%dT%H%M%SZ) + out="backups/fleet-$stamp" + mkdir -p "$out" + cp fleet.yaml .env "$out/" + chmod 600 "$out/.env" + for vol in openclaw hermes claude warden fleet-secrets engram-homes; do + docker run --rm -v "fleet_${vol}:/v:ro" -v "$PWD/$out:/out" alpine \ + tar -czf "/out/${vol}.tgz" -C /v . 2>/dev/null && info "saved $vol" + done + if memory_enabled; then + compose exec -T db pg_dumpall -U postgres | gzip > "$out/engram-db.sql.gz" && info "saved memory database" + fi + bold "backup written to $out" +} + +cmd_help() { + cat <<'EOF' +fleet: run your AI agent fleet + + setup answer a few questions; writes fleet.yaml and .env + up start or apply changes to fleet.yaml / .env + login claude connect a Claude Pro/Max subscription + login chatgpt connect a ChatGPT Plus/Pro subscription + whatsapp pair WhatsApp for an agent (scan a QR code) + pair approve someone who messaged an agent + status what is running + logs [service] follow logs (openclaw, hermes, engram, init) + ui how to open the dashboards + update pull the latest fleetkit and restart + backup snapshot config, logins, sessions and memory + down stop everything (data is kept) + + openclaw run the OpenClaw CLI inside the fleet + hermes run the Hermes CLI for one agent +EOF +} + +case "${1:-help}" in + setup) cmd_setup ;; + up) cmd_up ;; + down) need_setup; export_profiles; compose down ;; + status|ps) cmd_status ;; + logs) need_setup; export_profiles; shift; compose logs -f --tail 100 "$@" ;; + login) shift; cmd_login "$@" ;; + whatsapp) shift; cmd_whatsapp "$@" ;; + pair) shift; need_setup; compose exec -it openclaw openclaw pairing approve "$@" ;; + ui) cmd_ui ;; + update) cmd_update ;; + backup) cmd_backup ;; + openclaw) shift; need_setup; compose exec -it openclaw openclaw "$@" ;; + hermes) shift; need_setup; aid="${1:?usage: ./fleet hermes }"; shift; hermes_exec "$aid" "$@" ;; + help|-h|--help) cmd_help ;; + *) cmd_help; exit 1 ;; +esac diff --git a/fleet.example.yaml b/fleet.example.yaml new file mode 100644 index 0000000..59ede4a --- /dev/null +++ b/fleet.example.yaml @@ -0,0 +1,64 @@ +# fleet.yaml: who your agents are and where they live. +# +# `./fleet setup` writes this file for you. Edit it by hand any time, then run +# `./fleet up` to apply. Secrets (bot tokens) never go here; they live in .env. + +owner: + name: Sam + # IANA timezone, used for heartbeats, quiet hours and the warden schedule. + timezone: Europe/London + +# AI subscriptions you sign in to. No API keys, no per-token billing. +# claude Claude Pro or Max → `./fleet login claude` +# chatgpt ChatGPT Plus or Pro → `./fleet login chatgpt` +# Agents fall back across these when one hits its usage limit. +subscriptions: [claude, chatgpt] + +# Each agent runs on one harness and talks on one or more chat platforms. +# +# harness openclaw | hermes +# role ops | builder | assistant | researcher | custom +# (picks the starter persona from templates/roles/.md) +# model optional override, e.g. anthropic/claude-opus-4-8 or +# openai/gpt-5.6-sol. Defaults come from your subscriptions. +# channels any of: discord, telegram, whatsapp +# +# Each agent with a chat channel needs its own bot. Tokens are read from .env: +# discord DISCORD_TOKEN_ (e.g. DISCORD_TOKEN_OPS) +# telegram TELEGRAM_TOKEN_ (e.g. TELEGRAM_TOKEN_ASSISTANT) +# whatsapp no token: pair once with `./fleet whatsapp ` (QR code) +# +# WhatsApp links a real phone number, so give it to one agent per harness. +agents: + - id: ops + name: Ops + harness: openclaw + role: ops + channels: [discord] + + - id: builder + name: Builder + harness: openclaw + role: builder + channels: [discord] + + - id: assistant + name: Assistant + harness: hermes + role: assistant + channels: [telegram] + +defaults: + # How often OpenClaw agents wake to check HEARTBEAT.md. "0m" turns it off. + heartbeat: 1h + # Agents stay quiet outside these hours unless something is urgent. + active_hours: { start: "08:00", end: "22:00" } + +memory: + # Shared long-term memory across every agent (engram + gbrain on Postgres). + enabled: true + +warden: + # session-warden: rotates bloated sessions, guards rate limits, runs nightly + # reflection and weekly reviews. Turn off to run the agents bare. + enabled: true From e578ff94b8226461f55541797a38d1f8a3461cc9 Mon Sep 17 00:00:00 2001 From: Ani Date: Wed, 7 Oct 2026 11:46:08 +0530 Subject: [PATCH 3/5] feat: one-line VPS installer and cloud-init Co-authored-by: Cursor --- cloud-init.yaml | 15 +++++++++++++ install.sh | 60 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+) create mode 100644 cloud-init.yaml create mode 100755 install.sh 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/install.sh b/install.sh new file mode 100755 index 0000000..e33912b --- /dev/null +++ b/install.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# Install fleetkit on a fresh Ubuntu or Debian server: +# curl -fsSL https://raw.githubusercontent.com/Ani-HQ/fleetkit/main/install.sh | bash +set -euo pipefail + +REPO="${FLEETKIT_REPO:-https://github.com/Ani-HQ/fleetkit.git}" +BRANCH="${FLEETKIT_BRANCH:-main}" +DIR="${FLEETKIT_DIR:-$HOME/fleetkit}" + +say() { printf '\033[1m==> %s\033[0m\n' "$*"; } +die() { printf 'install: %s\n' "$*" >&2; exit 1; } + +SUDO="" +if [ "$(id -u)" != 0 ]; then + command -v sudo >/dev/null || die "run as root or install sudo" + SUDO="sudo" +fi + +[ -r /etc/os-release ] && . /etc/os-release +case "${ID:-}${ID_LIKE:-}" in + *debian*|*ubuntu*) ;; + *) die "this installer supports Ubuntu and Debian. Elsewhere: install Docker + git, clone $REPO, run ./fleet setup" ;; +esac + +mem_mb=$(awk '/MemTotal/{print int($2/1024)}' /proc/meminfo) +[ "$mem_mb" -ge 3500 ] || printf ' ! %s MB RAM. 4 GB is the minimum for the full fleet.\n' "$mem_mb" + +say "installing packages" +$SUDO apt-get update -qq +$SUDO apt-get install -y -qq git openssl python3 ca-certificates curl >/dev/null + +if ! command -v docker >/dev/null; then + say "installing Docker" + curl -fsSL https://get.docker.com | $SUDO sh >/dev/null +fi +$SUDO systemctl enable --now docker >/dev/null 2>&1 || true +if [ -n "$SUDO" ] && ! id -nG | grep -qw docker; then + $SUDO usermod -aG docker "$(id -un)" + NEED_RELOGIN=1 +fi + +if [ -d "$DIR/.git" ]; then + say "updating $DIR" + git -C "$DIR" pull --ff-only +else + say "cloning fleetkit into $DIR" + git clone --depth 1 --branch "$BRANCH" "$REPO" "$DIR" +fi + +say "done" +echo +if [ -n "${NEED_RELOGIN:-}" ]; then + echo " Log out and back in once (so Docker works without sudo), then:" +else + echo " Next:" +fi +echo " cd $DIR" +echo " ./fleet setup" +echo " ./fleet up" +echo " ./fleet login claude # and/or: ./fleet login chatgpt" From 001ab39854c2040c965657df6c3562836321b45b Mon Sep 17 00:00:00 2001 From: Ani Date: Wed, 7 Oct 2026 11:46:08 +0530 Subject: [PATCH 4/5] docs: quickstart, deploy, subscriptions, channels, security Co-authored-by: Cursor --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++- docs/channels.md | 54 +++++++++++++++++++++++++++++ docs/deploy.md | 75 ++++++++++++++++++++++++++++++++++++++++ docs/security.md | 27 +++++++++++++++ docs/subscriptions.md | 51 +++++++++++++++++++++++++++ docs/upgrading.md | 42 +++++++++++++++++++++++ 6 files changed, 328 insertions(+), 1 deletion(-) create mode 100644 docs/channels.md create mode 100644 docs/deploy.md create mode 100644 docs/security.md create mode 100644 docs/subscriptions.md create mode 100644 docs/upgrading.md 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/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-