clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 33
colibri/docs/guide/install/requirements.md
Sam & Claude 123f86196d
Some checks are pending
CI / rust (pull_request) Waiting to run
Details
CI / markdown (pull_request) Waiting to run
Details
CI / port (pull_request) Waiting to run
Details
CI / agent-jail-pkgs (pull_request) Waiting to run
Details
docs(guide): correct install docs to the clawdie binary (not just/clawdie-ai) 
The install/ section was clawdie-ai docs ported into colibri: it documented a
`just install` Node/tsx 20-step orchestrator + Ansible, none of which exists
here (colibri is a Cargo workspace). colibri's real installer is the `clawdie`
binary (crates/clawdie): `discover` / `plan` / `apply --yes` → ZFS datasets +
clawdie service user + rc.d/systemd unit running colibri-daemon.

- install.md: rewritten to the clawdie flow (commands, storage strategy,
  what apply provisions, --create-pool safety) from crates/clawdie/README.md.
  Adds a Scope section marking PF/jails/PostgreSQL/CMS provisioning as legacy
  clawdie-ai (not yet in the colibri installer) — no invented commands.
- controlplane-install.md: rewritten to `cargo build -p clawdie` + apply.
- index.md: "Install orchestrator / just install" → clawdie discover/plan/apply.
- requirements.md: toolchain → Cargo/clawdie (drop Node/tsx), install command
  fixed, and a note that the runtime-philosophy prose is still clawdie-ai
  pending reconciliation.

Out of scope (flagged for follow-up): first-boot.md (ISO QML rewrite pending),
fresh-install-checklist.md, and the `just install/setup/doctor` mentions in the
architecture pages — all broader clawdie-ai legacy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-26 10:50:08 +02:00

3 KiB
Raw Blame History

title description
Requirements Host, runtime, and toolchain requirements for Clawdie.

What you need on the host before installing Clawdie. The ISO installer provisions most of this automatically; existing-host installs should verify these requirements before running clawdie apply.

Host

  • OS: FreeBSD 15.x (jails are the only supported runtime).
  • Privileges: root or a user with sudo and ZFS access.
  • ZFS: required for Bastille jails. Snapshots are taken at install milestones if zroot/bastille exists; skipped silently otherwise.
  • Network: outbound HTTPS for package install, LLM provider, and Telegram. PF egress NAT is configured by the installer.

Toolchain

  • Rust (Cargo) — the colibri control plane and the clawdie installer are a Cargo workspace. Build the installer with cargo build -p clawdie --release. See Install.
  • Bastille for jail management.

The legacy clawdie-ai just + Node/tsx orchestrator is not used in this repo; the sections below still describe the clawdie-ai product runtime and are being reconciled to the colibri model.

Runtime philosophy

Clawdie is a single Node.js process that orchestrates jailed agents. The design commitments that shape what you need:

  • Security through OS-level isolation. Agents run inside FreeBSD jails. Bash access is safe because it executes inside the jail, not on the host. Filesystem access is limited to explicitly mounted paths.
  • Small enough to read. No microservices, no message queues, no abstraction layers. One process, a handful of source files.
  • AI-native operations. The codebase assumes you have an AI collaborator. Operator-facing tools (dashboard, monitoring) are thin; the assistant fills in by answering questions about logs, state, and configuration directly.
  • Customization = code changes. Trigger word and a few core settings live in .env. Anything else: edit the code. The codebase is small enough that this is safe.

Integration surfaces

  • Telegram via the Bot API (grammy). The primary I/O channel.
  • PostgreSQL for operations, memory, and built-in knowledge databases. The default is host runtime (DB_RUNTIME=host); set DB_RUNTIME=jail to provision a dedicated db jail instead.
  • LLM provider of your choice. OpenRouter is the recommended bootstrap path; switch post-install to direct provider keys (zAI, Anthropic, OpenAI, Gemini), or local Ollama by editing .env. See Provider Fallback for the cap-detection and fallback behavior.

Skills extension model

Skills are how operators add capabilities without forking core. Common skill shapes:

  • Communication channels (/add-slack, /add-discord, etc.) to extend beyond Telegram.
  • Browser automation via agent-browser running inside a jail.
  • Scheduled tasks registered against the per-group context.

Skills install into data/skills/ and are loaded at startup.