clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 31
colibri/docs/guide/install/requirements.md
Sam & Claude 79f67bf575
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 clawdie binary (not just/Ansible) 
Replace legacy just install / just setup-* references with
clawdie binary commands (clawdie plan, clawdie apply --yes).
Document scope: what the installer does not do (yet).
Trim the clawdie-ai just orchestrator step tables.

Rebased from #213 onto current main; supersedes #217.
2026-06-26 15:00:34 +02:00

3 KiB
Raw Permalink 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.