README
¶
Rookery
Self-hosted AI agents that run on your own machine, around the clock.
Rookery is a single binary. It keeps your knowledge as plain markdown on your own disk, builds agents from a conversation rather than a config file, reaches 136 external services with credentials you own, and talks to you on Telegram, Discord or Slack. The database is SQLite, secrets are encrypted at rest, and coder subprocesses are confined with Landlock on Linux.
Full documentation lives at rookery.cloud/docs.
Quickstart
curl -fsSL https://rookery.cloud/install.sh | sh
On Windows, in PowerShell:
irm https://rookery.cloud/install.ps1 | iex
The installer puts a verified binary on your PATH and offers the host tools
Rookery degrades without. Then set the install up:
rookery onboard
Open http://localhost:8080, log in, and create your first workspace.
While this repository is private,
curl | shreturns404— release assets need an authenticated request. Build from source until the public release.
Build from source instead
Requires Go 1.26 and Node 24.
make build
./bin/rookery owner bootstrap -u <username> -p <password>
./bin/rookery serve
Run the container instead
podman run -d --name rookery -p 8080:8080 \
-v rookery-data:/data ghcr.io/rookery-ai/rookery:latest
The image is slim: it ships no CLI coder binary and sets
ROOKERY_CODER_MODE=slim, so workspaces must use the api coder kind.
What it's like
You — Every morning, tell me if any of my sites went down overnight.
Rookery — Two quick questions. Which sites should I watch, and should I message you every morning or only when something is actually wrong?
You — rookery.cloud and my blog. Only when something is wrong.
Rookery — Here is the agent I will build:
- Checks both sites every morning at 7am
- Messages you only if one is unreachable or slow
- Writes every check into your notes, under Uptime
Type approve and I will build it and test it for real.
You — approve
It then writes the agent, runs it against the real services, reports what came back, and saves only once you have seen that.
Workspaces
One machine. Sealed, separate worlds.
Every workspace is its own tenant — its own knowledge, its own credentials, its own connected accounts, its own agents. You enter one with its password, and nothing crosses between them.
Knowledge base
Everything you know, as plain markdown on your own disk.
What you write, what your agents learn, and what your connected services bring in, all in one vault. Open it in Rookery or in any editor you like. Agents read the whole vault and write durable knowledge back into it across runs.
Agents
Describe it. Don't configure it.
Say what you want in your own words. Rookery asks a couple of questions, proposes a plan, builds it, tests it against the real services, and shows you what happened before anything is saved. Then it just runs.
Skills
Things your agents already know how to do.
22 built in and ready to attach to any agent — reading PDFs and spreadsheets, web research, browser automation, git, email triage — plus any you create the same conversational way.
Every agent gets the same tools, whatever model is behind it. A small model on your own machine and a frontier one are given the same reach. The model decides how well a job is done — never whether it can be done at all.
Connections
136 services. No middleman holding your keys.
Rookery talks to them directly, using credentials you own: 136 providers and 934 curated actions, over OAuth or an API key you paste — never a broker.
Google, GitHub, Notion, Slack, Jira, Stripe, Shopify — and the self-hosted tier too: Home Assistant, Immich, Paperless-ngx, Nextcloud, Jellyfin.
MCP servers
Not on the list? Add it yourself.
Point Rookery at any Model Context Protocol server by URL — including one running on your own network — and its tools become available to your agents and to chat. Nothing about the server ships with Rookery: you supply the URL, it supplies its own tool list. That is the one thing a curated connection cannot do, because it does not wait for a release.
You decide which of its tools are switched on, which may run while an agent is being built, and which need your approval first.
Chat
Ask what you know. Then have it act.
Talk to your knowledge the way you'd talk to someone who has read all of it — and have it write a note, or do something in a connected account, right there in the conversation.
Notifications
You find out the moment it happens.
An agent finished, a service returned something new, a reminder came due. It lands in your inbox, and reaches you on Telegram, Discord or Slack when you're away.
Models
Your machine. Your model.
Use the coder tool you already have, or connect the provider you prefer — hosted, or running entirely on your own hardware. Nothing ties you to one vendor.
Secrets
Credentials that stay yours.
Encrypted where they sit, unlocked only into the thing that needs them, scoped to one workspace, and never handed to anyone else.
Scheduling
Every weekday at eight. And again at ten.
Say when in your own words — twice a day, every Monday at nine, every twenty minutes during work hours, or only when you ask. Reminders work the same way: remind me in 10 minutes to call the doctor.
How it fits together
Configuration
| Variable | Default | Purpose |
|---|---|---|
ROOKERY_HOST |
0.0.0.0 |
bind address; 127.0.0.1 for loopback-only |
ROOKERY_PORT |
8080 |
listen port |
ROOKERY_DATA_DIR |
~/.rookery |
data root; also relocates the database |
ROOKERY_SESSION_KEY |
generated, then pinned to <data_dir>/session.key |
hex 32-byte session key |
ROOKERY_SYSTEM_KEY |
generated | hex key encrypting stored credentials |
ROOKERY_PUBLIC_URL |
— | externally reachable base URL for OAuth callbacks |
ROOKERY_SANDBOX |
1 |
0/false/off disables Landlock confinement |
ROOKERY_CODER_MODE |
full |
slim removes the local CLI coder kind |
ROOKERY_CLAUDE_BIN |
claude |
override the path to a coder binary |
ROOKERY_PUBLIC_URL matters more than it looks: OAuth providers reject redirect
URIs on non-public hostnames, so a .lan address fails Google's validation. Use
a real hostname — rookery.cloud is the documented example — or http://localhost.
Platform support
| Target | Sandbox | Service |
|---|---|---|
| linux amd64/arm64 | Landlock | systemd user unit |
| container (linux) | Landlock | runtime-managed |
| darwin amd64/arm64 | none | launchd (not yet shipped) |
| windows amd64/arm64 | none | SCM (not yet shipped) |
Off Linux there is no filesystem sandbox: coder subprocesses run unconfined.
/healthz and the startup log both report this.
Health
GET /healthz is unauthenticated and reports version, commit, sandbox status
including the Landlock ABI, coder mode and host-tool presence. A python3
warning is not cosmetic — without it the agent-tool AST guardrail self-skips, so
generated tool scripts run unchecked.
Contributing
Branch off main; main only ever advances through merged pull requests. Use
Conventional Commits — the PR title
becomes the squashed commit and drives release versioning. Run the full gate
locally before opening a PR:
make ci
License
Apache-2.0. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
livecheck
command
Command livecheck exercises every read (and safe-write) connector action against the REAL provider APIs using the stored tokens, so we can confirm the whole surface works — not just the one path an agent happened to use.
|
Command livecheck exercises every read (and safe-write) connector action against the REAL provider APIs using the stored tokens, so we can confirm the whole surface works — not just the one path an agent happened to use. |
|
rookery
command
|
|
|
internal
|
|
|
agentdesigner
Package agentdesigner implements the conversational agent creation wizard.
|
Package agentdesigner implements the conversational agent creation wizard. |
|
agentrunner
Package agentrunner loads an agent from disk and executes it via the coder CLI.
|
Package agentrunner loads an agent from disk and executes it via the coder CLI. |
|
approval
Package approval implements the run-time gate for irreversible public writes.
|
Package approval implements the run-time gate for irreversible public writes. |
|
awssig
Package awssig signs HTTP requests with AWS Signature Version 4.
|
Package awssig signs HTTP requests with AWS Signature Version 4. |
|
backup
Package backup snapshots an entire Rookery install — the database and every workspace vault — into one passphrase-encrypted file, and restores it.
|
Package backup snapshots an entire Rookery install — the database and every workspace vault — into one passphrase-encrypted file, and restores it. |
|
buildinfo
Package buildinfo carries the version metadata stamped into the binary at link time.
|
Package buildinfo carries the version metadata stamped into the binary at link time. |
|
buildphase
Package buildphase defines the marker that tells the coder engine a run is an agent/skill BUILD (generation/verification), not a real scheduled/manual run.
|
Package buildphase defines the marker that tells the coder engine a run is an agent/skill BUILD (generation/verification), not a real scheduled/manual run. |
|
chat
Package chat provides the background auto-stop service for chats and the shared user-context builder used by both the Telegram gateway and the web chat composer when invoking the coder for one-off conversational turns.
|
Package chat provides the background auto-stop service for chats and the shared user-context builder used by both the Telegram gateway and the web chat composer when invoking the coder for one-off conversational turns. |
|
coder
Package coder wraps any compatible coder CLI as the code generation engine.
|
Package coder wraps any compatible coder CLI as the code generation engine. |
|
connalert
Package connalert delivers "this connection needs reconnecting" notices to the two surfaces a workspace owner actually watches.
|
Package connalert delivers "this connection needs reconnecting" notices to the two surfaces a workspace owner actually watches. |
|
connectors
Package connectors owns the self-managed-OAuth connector layer: per-provider OAuth configs + curated action manifests (embedded data files), and the typed Execute path agents call.
|
Package connectors owns the self-managed-OAuth connector layer: per-provider OAuth configs + curated action manifests (embedded data files), and the typed Execute path agents call. |
|
convert
Package convert turns document bytes into markdown.
|
Package convert turns document bytes into markdown. |
|
export
Package export turns a KB markdown note into a downloadable document — HTML, DOCX, or PDF.
|
Package export turns a KB markdown note into a downloadable document — HTML, DOCX, or PDF. |
|
fonts
Package fonts holds the single copy of the UI font.
|
Package fonts holds the single copy of the UI font. |
|
gateway
Package gateway provides the platform-agnostic message routing layer.
|
Package gateway provides the platform-agnostic message routing layer. |
|
gateway/render
Package render converts neutral CommonMark (emitted by the gateway router) into each chat platform's native markup.
|
Package render converts neutral CommonMark (emitted by the gateway router) into each chat platform's native markup. |
|
health
Package health builds the capability report served at /healthz and logged at startup.
|
Package health builds the capability report served at /healthz and logged at startup. |
|
iolimit
Package iolimit holds the ONE shared "read at most N+1 bytes, then reject if over" pattern for every door into the system that receives a document, attachment, or request body whose size is caller-controlled and could be arbitrarily large.
|
Package iolimit holds the ONE shared "read at most N+1 bytes, then reject if over" pattern for every door into the system that receives a document, attachment, or request body whose size is caller-controlled and could be arbitrarily large. |
|
llm
Package llm provides direct LLM provider HTTP transport — a thin, reusable abstraction over chat-completion / messages APIs with native function-calling (tool use).
|
Package llm provides direct LLM provider HTTP transport — a thin, reusable abstraction over chat-completion / messages APIs with native function-calling (tool use). |
|
mcp
Package mcp is Rookery's Model Context Protocol client layer.
|
Package mcp is Rookery's Model Context Protocol client layer. |
|
memory
Package memory provides a per-user store for structured context files.
|
Package memory provides a per-user store for structured context files. |
|
nethttp
Package nethttp holds a single, shared dial-control primitive for outbound HTTP clients that must refuse to reach private/loopback address space.
|
Package nethttp holds a single, shared dial-control primitive for outbound HTTP clients that must refuse to reach private/loopback address space. |
|
onboard
Package onboard holds the platform knowledge behind `rookery onboard`: which host tools a working install wants, what each package manager calls them, and how the server is expected to run on each operating system.
|
Package onboard holds the platform knowledge behind `rookery onboard`: which host tools a working install wants, what each package manager calls them, and how the server is expected to run on each operating system. |
|
profile
Package profile stores and renders per-user personalization data (name, location, timezone, communication tone, etc.) collected during onboarding and editable later from Settings.
|
Package profile stores and renders per-user personalization data (name, location, timezone, communication tone, etc.) collected during onboarding and editable later from Settings. |
|
prompts
Package prompts centralizes all LLM prompt construction for the coder CLI.
|
Package prompts centralizes all LLM prompt construction for the coder CLI. |
|
publicurl
Package publicurl owns the instance's externally-reachable base URL and judges it against a provider's redirect-URI policy.
|
Package publicurl owns the instance's externally-reachable base URL and judges it against a provider's redirect-URI policy. |
|
reminder
Package reminder polls for due reminders and delivers them via the gateway.
|
Package reminder polls for due reminders and delivers them via the gateway. |
|
sandbox
Package sandbox provides a self-contained, dependency-free filesystem confinement for coder subprocesses using the Linux Landlock LSM.
|
Package sandbox provides a self-contained, dependency-free filesystem confinement for coder subprocesses using the Linux Landlock LSM. |
|
scheduler
Package scheduler polls for due agent schedules and fires agent runs.
|
Package scheduler polls for due agent schedules and fires agent runs. |
|
secrets
Package secrets provides per-user AES-256-GCM encrypted secret storage.
|
Package secrets provides per-user AES-256-GCM encrypted secret storage. |
|
skilldesigner
Package skilldesigner implements the conversational skill-creator wizard.
|
Package skilldesigner implements the conversational skill-creator wizard. |
|
skilllibrary
Package skilllibrary embeds the core skill catalog — the adapted, standards-based defaults shipped with the binary and always-on for every user.
|
Package skilllibrary embeds the core skill catalog — the adapted, standards-based defaults shipped with the binary and always-on for every user. |
|
skillstore
Package skillstore manages per-user Agent Skills (agentskills.io format).
|
Package skillstore manages per-user Agent Skills (agentskills.io format). |
|
vault
Package vault implements a per-user Obsidian-style knowledge base: a single directory of interlinked markdown notes that holds (almost) everything a user owns — notes, journals, plans, memory, agent definitions, run logs, chat transcripts and reflected database rows — browsable from the web UI, searchable, and readable by the user's agents.
|
Package vault implements a per-user Obsidian-style knowledge base: a single directory of interlinked markdown notes that holds (almost) everything a user owns — notes, journals, plans, memory, agent definitions, run logs, chat transcripts and reflected database rows — browsable from the web UI, searchable, and readable by the user's agents. |
|
websearch
Package websearch turns a query into web results using a cascade of providers.
|
Package websearch turns a query into web results using a cascade of providers. |
|
Package migrations carries the SQL schema migrations compiled into the binary.
|
Package migrations carries the SQL schema migrations compiled into the binary. |
|
ui
Package ui embeds the built single-page app (web/ui/dist).
|
Package ui embeds the built single-page app (web/ui/dist). |