Skip to content
Clawdie

Requirements

What you need on the host before installing Clawdie. For the ISO/V1 first-boot path most of this is provisioned automatically — this page is the contract for existing-host installs and for understanding what the installer expects.

Host

Section titled “Host”
  • OS: FreeBSD 14.x (jails are the only supported runtime).
  • Privileges: root or a user with sudo and ZFS access.
  • ZFS: recommended. 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

Section titled “Toolchain”
  • Rust via rustup, installed under /opt/clawdie/rustup. Required for native dependencies (SWC, tree-sitter). The ISO installs this; existing-host installs run it from Install orchestrator.
  • Node.js + tsx for the install scripts and runtime.
  • Bastille for jail management.

Runtime philosophy

Section titled “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

Section titled “Integration surfaces”
  • Telegram via the Bot API (grammy). The primary I/O channel.
  • PostgreSQL for the operations database. Runs in a jail by default; set DB_RUNTIME=host to provision on the host instead.
  • LLM provider of your choice. OpenRouter is the recommended bootstrap path; switch to direct provider keys (zAI, Anthropic, OpenAI, Gemini) post-install via /model or by editing .env. See Provider Fallback for the cap-detection and fallback behavior.

Skills extension model

Section titled “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.