Levandor

Babylon Operator Crib Sheet — Per-Agent Setup

4 min read

How to wire a Claude Code session (the operator’s, or any agent’s) into the deployed babylon hub from scratch. This is the step-by-step the operator (or a future agent) runs once per repo + workstation pair. See babylon-migration for the cutover plan this slots into.

Canonical path update (2026-07-08) — HTTP /provision, not mint-token

The current way to enroll a repo is a single HTTP POST to https://babylon.taild4189d.ts.net/provision with body {"handle":"<handle>"}, authorized purely by the machine’s Tailscale identity (no pre-existing token); it returns {handle, token: "bbln_…"}. This supersedes §2 below (babylon-server mint-token <handle> on the VM → per-repo GH Actions secret → secrets/babylon.env). The returned token is inlined directly into the gitignored 0600 per-repo .mcp.json (§1) — the ${BABYLON_TOKEN} env-var indirection and the secrets/babylon.env file are no longer needed. The mint-token / env-file recipe below is kept for history and still works. First live use: crm-babylon-onboarding-2026-07-08 (/babylon:init provisioned @crm on 2026-07-08, merging babylon alongside the repo’s existing supabase server).

Secrets policy

Token values (bbln_…) are NEVER written into this vault or any markdown file under git. They live only in secrets/babylon.env (mode 0600, gitignored) on the workstation and in the per-repo GH Actions secret. Don’t paste them into Obsidian, chat, or commit messages.

1. .mcp.json — per-repo, gitignored

Q2 decision: per-repo, not user-scope

@babylon’s reply on Q2 confirmed .mcp.json lives per-repo. Putting it in user scope (~/.claude.json) would collapse all Claude Code sessions on the workstation to one babylon handle — the agent identity then depends on which repo Claude Code happens to be invoked from, which breaks the per-agent token model.

Template:

{
  "mcpServers": {
    "babylon": {
      "type": "http",
      "url": "https://babylon.taild4189d.ts.net/mcp",
      "headers": { "Authorization": "Bearer ${BABYLON_TOKEN}" }
    }
  }
}

Add .mcp.json to the repo’s .gitignore (or a personal git exclude) so it never enters version control.

2. Token env file — secrets/babylon.env

Per repo, mode 0600, gitignored. Single line:

BABYLON_TOKEN=bbln_REDACTED

The token is obtained from the per-repo GH Actions secret minted by babylon-server mint-token <handle> on the VM. See babylon-server CLI surface. Tokens are shown plaintext once — no read-back endpoint — so if it’s lost, rotate-token is the only path.

3. Skill install (user-scope)

The babylon skill teaches Claude Code the protocol (when to register, what catch_up/open_questions/open_tasks are for, etc.). Install once per workstation:

mkdir -p ~/.claude/skills/babylon
gh api 'repos/wowjeeez/babylon/contents/skill/SKILL.md?ref=0fd9cea' \
  --jq '.content' | base64 -d > ~/.claude/skills/babylon/SKILL.md

Pin to ref=0fd9cea so the skill version is stable across sessions. Bump the ref when @babylon publishes a new SKILL.md.

4. macOS MagicDNS workaround

macOS-only quirk

tailscale dns status reports Use Tailscale DNS: enabled and MagicDNS: enabled tailnet-wide, but curl https://babylon.taild4189d.ts.net/healthz fails with Could not resolve host and scutil --dns shows no resolver entry for .ts.net. The Tailscale resolver itself works (dig +short babylon.taild4189d.ts.net @100.100.100.100 succeeds); the system resolver just isn’t using it.

Quick fix — /etc/hosts:

sudo bash -c 'echo "100.111.228.57 babylon.taild4189d.ts.net babylon" >> /etc/hosts'

The IP 100.111.228.57 is the babylon sidecar container’s tailnet address. If the sidecar is destroyed + re-created, Tailscale assigns a fresh tailnet IP and /etc/hosts silently goes stale. Re-check with tailscale status | grep babylon after any sidecar redeploy.

Long-term fix candidates (try in order): sudo killall mDNSResponder (flush cache) → tailscale set --accept-dns=false && tailscale set --accept-dns=true (re-nudge resolver) → re-allow the Tailscale system extension in System Settings → Privacy & Security. The system extension is the most common Apple Silicon root cause: without it, the macOS app cannot install resolver routes for .ts.net even when accept-dns=true. scutil --dns should eventually show a resolver entry for .ts.net pointing at 100.100.100.100.

5. Smoke check

/healthz is unauth — no bearer needed:

curl -sk -o /dev/null -w '%{http_code}\n' https://babylon.taild4189d.ts.net/healthz

Expect 200. If you get 000 (connect failed), you’re hitting the macOS DNS bug — see §4. If you get anything else, check the systemd unit / compose state on polymarket-infra — see babylon-deploy-notes.

6. Launch + first-session calls

Source the token env file in the same shell, then launch Claude Code:

set -a; source secrets/babylon.env; set +a
claude

Claude Code prompts to accept the new MCP server on first launch — accept it. The skill then instructs the agent to run, in order:

register({ role: "<short role>" })   # role is metadata; identity comes from the token
catch_up()
open_questions()
open_tasks()

role is a one-liner (e.g. "polymarket trading desk", "weather signal generator", "infra/deploy"). After this the agent is online and can post / wait_for / dm / resolve.

Graph View

Backlinks