README
¶
Rookery is a platform for agents that work on your behalf, running on hardware you own. You install one program. It gives you:
- A place to keep what you know — as plain markdown on your own disk.
- A way to build agents by describing them in plain language.
- A way for those agents to reach the services you already use — email, calendars, repositories, home automation, whatever you connect.
They run on a schedule, or when you ask, and they tell you what happened. The whole thing is designed to sit on a machine that stays on, so the work carries on while you are not watching.
Quickstart
curl -fsSL https://rookery.cloud/install.sh | sh
rookery onboard
Then open http://localhost:8899, log in, and create your first workspace.
Windows
irm https://rookery.cloud/install.ps1 | iex
rookery onboard
iex cannot pass arguments, so a specific version needs a script block:
& ([scriptblock]::Create((irm https://rookery.cloud/install.ps1))) -Version v0.2.0.
Windows has no filesystem confinement. Autostart is a Task Scheduler logon task
that rookery service registers for you — see
the Windows guide.
Container
docker run -d --name rookery -p 8899:8899 \
-v rookery-data:/data ghcr.io/rookery-ai/rookery:latest
The image is slim — no CLI coder binary, ROOKERY_CODER_MODE=slim — so
workspaces must use the api coder kind.
Build from source
Requires Go 1.26 and Node 24.
make build
./bin/rookery owner bootstrap -u <username> -p <password>
./bin/rookery serve
What you get
100+ services and 900+ curated actions, over OAuth or an API key you paste — never a broker. 22 skills built in, plus any you create the same conversational way.
Read more — Workspaces · Knowledge base · Agents · Browser · Skills · Connections · MCP servers · Chat · Notifications · Models · Secrets · Scheduling
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 |
8899 |
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_BROWSER_ALLOW_PRIVATE |
0 |
1/true/on lets the headless browser reach private/loopback addresses (e.g. a self-hosted dashboard). Off by default — see the browser guide |
ROOKERY_CODER_MODE |
full |
slim removes the local CLI coder kind |
ROOKERY_CODER_BIN |
claude |
default coder binary for workspaces that have not chosen one |
ROOKERY_CLAUDE_BIN |
— | deprecated alias for ROOKERY_CODER_BIN; still honoured, warns at startup |
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 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 user agent (at login) |
| windows amd64/arm64 | none | Task Scheduler logon task |
Off Linux there is no filesystem sandbox — coder subprocesses run
unconfined. GET /healthz reports that, along with version, coder mode and
host-tool presence; a python3 warning there is not cosmetic, because without
it the agent-tool AST guardrail self-skips.
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. Push the branch and
read the result from CI rather than reproducing it locally; make ci-fmt,
ci-vet, ci-ui and ci-docs are the quick targeted checks worth running
first.
License
Apache-2.0, permanently. See LICENSE.
There is no contributor licence agreement. Without one, nobody — the maintainers included — can relicense this project unilaterally, which makes the line above a structural fact about the repository rather than a statement of intent.
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. |
|
agentstate
Package agentstate owns the on-disk format of an agent's state.md — the markdown document that holds an agent's memory between runs.
|
Package agentstate owns the on-disk format of an agent's state.md — the markdown document that holds an agent's memory between runs. |
|
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. |
|
browser
Package browser renders web pages in a real, confined browser so the platform can read content that only exists after JavaScript runs.
|
Package browser renders web pages in a real, confined browser so the platform can read content that only exists after JavaScript runs. |
|
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). |
|
logsafe
Package logsafe makes a caller-supplied string safe to put in a log entry.
|
Package logsafe makes a caller-supplied string safe to put in a log entry. |
|
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. |
|
release
Package release resolves and verifies published Rookery release artifacts.
|
Package release resolves and verifies published Rookery release artifacts. |
|
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). |
Click to show internal directories.
Click to hide internal directories.