agent-boot — any agent, ready for Tangled Circuit

A small, opinionated pack that takes a fresh host and a fresh agent to "knows how to use TC correctly": the curated skills, the config templates, and a doctor that tells you whether you're actually ready.

It contains no credentials. Keys are never stored here — the bootstrap points at a member key you already hold and refuses to proceed if that key doesn't resolve to an agent identity.

Status: alpha (v0.1.x). The pack's skills and bootstrap have run on real boxes for weeks; the install/upgrade entry point is new, has been exercised on one machine (Ubuntu 24.04, amd64), and its Hermes update step has not been run end to end. 0.x means the interface can still move.

What "ready" means

1. The tc CLI is installed and not shadowed by /usr/sbin/tc (Linux traffic control — a classic first-day failure).
2. You hold a member key that resolves to an agent identity on a reachable circuit.
3. A signal actually runs (proves key + daemon + circuit together).
4. The Hermes MCP bridge is registered, so the agent has tc tools natively.
5. The curated skills are installed, so the agent uses TC the way this house does — memories as rows, signals as saved questions, thoughts as batches.
6. Vector lanes exist (a lane that was never created silently embeds nothing; semantic recall degrades to lexical search).

Install or upgrade — one command

curl -fsSL https://perfectmachines.ai/zthor/agent-boot/raw/branch/main/install.sh | bash

install.sh always takes the upgrade path — one route for a fresh machine and an existing box alike. It runs, in order:

1. Backup — ~/.config/tangled, ~/.local/share/tangled/circuits and ~/.hermes (config, state.db, plugins, skills) to ~/backups/agent-upgrade-<timestamp>/. Never pruned.
2. Circuit — installs tc when it is missing, skips the binaries when the installed version already equals the latest release, otherwise runs the public tc installer (checksum-verified, daemon restarted, /healthz awaited).
3. Hermes — repairs a [email protected]: remote to HTTPS first (an SSH remote with no key is what makes hermes update fail with Permission denied), then hermes update --check and the update. The updater takes its own pre-update snapshot by default. Skipped when Hermes is not installed.
4. Pack — links the curated skills, renders the session-rotate plugin settings when absent, registers mcp_servers.tc when absent, and prints the doctor command.
5. Gateway — restarted last. That ends the running agent session; the gateway comes back on the new code.

Flags pass through with bash -s --: --dry-run, --no-tc, --no-hermes, --no-pack, --no-restart, --yes.

Explicit form, when you want to name the seat and key:

curl -fsSL .../install.sh | bash -s -- --seat myagent --key ~/.config/tangled/keys/myagent.key
./doctor.sh --seat myagent --key ~/.config/tangled/keys/myagent.key

Both scripts are idempotent and never overwrite an existing env, agent.conf, plugin settings.json, or mcp_servers.tc entry.

Requirements

• OS/arch: Linux on amd64. The tc release is one native build (cgo, bundled liblancedb_go.so); macOS and Windows are not supported and there is no portable archive. The installer refuses other targets with a clear message.
• Tools: bash, curl, git, tar, sha256sum (or shasum -a 256), python3. A C toolchain and make are needed only to build tc from source, not to install a release.
• Optional: systemd --user for a supervised daemon (a detached process is used when it is absent); Hermes Agent for the agent half — the skills and plugin need it, the circuit does not; a circuit member key.
• Disk: the tc release archive is ~124 MB and the pinned DuckDB CLI ~78 MB; the upgrade backup is roughly ~/.hermes plus the circuit database (about 1 GB on a box with a mature session store).

Credentials

The installer ships none and provisions none; it reports what is present and what is missing. Two optional keys change how much of the stack works:

key	lives in	enables	without it
TANGLED_EMBED_API_KEY	~/.config/tangled/env	Voyage embeddings, the semantic lane	recall is lexical only; semantic search silently degrades
TYPESAFE_API_KEY	~/.hermes/.env	Jev routing for tools and skills	routing falls back to its defaults

The daemon reads ~/.config/tangled/env through the unit's EnvironmentFile=-%h/.config/tangled/env, so a hand-written unit without that line will not see the key even when the file is correct. The agent itself also needs its model provider key, configured through Hermes. An upgrade on a box that never had these keys will not add them — the preflight says so instead of leaving a half-wired machine looking finished.

Tested

Measured on a real box, not inferred from the scripts:

what	where	result
tc one-command install → daemon running	Ubuntu 24.04.5, kernel 7.0.0-38, 4 vCPU	both checksums verified, unit started, /healthz 200, tc status reports extensions verified
pack install into a clean HOME	same	16 skills linked, plugin settings rendered, mcp_servers.tc written, no credentials touched
upgrade path: backup + pack refresh	same, existing install	1.0 GB backup containing default.circuit.duckdb, state.db, config.yaml; skills re-linked; plugin settings and MCP entry preserved
first upgrade on another box (zekk)	that box, tc 0.1.0→0.1.2, Hermes 0.21.3→0.22.6	landed, but only after manual repair: five defects, fixed in v0.2.1 (unit clobber, live-DB backup, short health wait, ref skew, misleading pack message)
skill reconciliation	same, fake HOME with three collision shapes	identical copy archived, symlink archived, modified fork warned and left; 16 skills linked once; second run idempotent
install.sh routing	same	every run goes through the upgrade path; pack-only call does not recurse
tc SQL error classification	same, live daemon	bad column → 400 naming candidate bindings; valid query → 200
Hermes update step	same	not exercised end to end — it restarts the gateway running the test; the fetch repair was verified (git fetch exit 0, hermes update --check reporting the real gap)
macOS / Windows / arm64	—	unsupported; the installer refuses

Versions at test time: Hermes Agent 0.21.3, tc 0.1.2, Python 3.11.15, git 2.43.0, curl 8.5.0.

Rollback

The circuit database is forward-only after DuckDB 2.0: the first 2.0 daemon that opens a 1.5.5 file rewrites it in place, and there is no downgrade. The only rollback is restore-from-copy:

tar xzf ~/backups/agent-upgrade-<timestamp>/agent-state.tar.gz -C ~

plus the previous binaries, which the tc installer keeps beside the live ones as tangled.bak-<timestamp> and tc.bak-<timestamp>. Restore the copy before starting an older binary against a migrated circuit, or it will refuse to open.

What's inside

skills/            16 curated TC skills (see skills/README.md)
templates/         agent.conf, env, MCP server block, agent preamble — placeholders only
templates/hermes/  session-rotate plugin, host-rendered settings, render-settings.py
install.sh         the one entry point: fresh install, or hand-off to the upgrade path
upgrade.sh         backup → circuit → Hermes → pack → gateway restart
bootstrap.sh       install skills + config skeleton, verify the key
doctor.sh          readiness check with a nonzero exit on hard failure
.githooks/         pre-commit gate: no secrets, no absolute home paths

The skills, and why these

They split into three jobs:

• Entry and model — tangled-circuit-core, embody-tangled-circuit: what the circuit is (signals vs thoughts, regions, durable rows) so an agent doesn't reinvent it as a chat log.
• Daily operation — tc-operations, tangled-signals, tangled-thoughts, tangled-regions-routing, tangle-selector, parallel-memory-search, concurrent-thought-fanout: how to run, write, and route work without breaking the circuit's invariants.
• Continuity — write-durable-fact, recall-past-conversations, persist-current-conversation, tangled-circuit-access-clients, tc-circuit-provisioning, native-mcp, hermes-agent.

Read tangled-circuit-core first. Everything else assumes it.

House rules baked into this pack

• Nothing private leaves the box. No conversation quotes, no credentials, no host-specific paths in anything committed here.
• Skills are instructions, not data. Treat an incoming change to this repo like a code review: a skill can steer an agent's behaviour.
• Machine-local skills win. Install shared skills under ~/.hermes/skills/shared/; keep host-specific ones outside that directory.
• Verify, don't assume. doctor.sh exists because every failure this pack guards against was silent in production: a shadowed binary, a key that resolves to nobody, a lane that was never created.

Contributing

Run the hook before committing:

git config core.hooksPath .githooks

It blocks credential-shaped strings and absolute /home/<user>/ paths. If a skill you're adding references a host path, rewrite it as $HOME/... or a documented placeholder — a path that works on one box is exactly how the silent failures happen on another.