Reference

Asylum documentation

Everything the app does and how to drive it. If you are starting from zero, the course is the better door — this page assumes you know what a fan-out is.

Concepts

Three nouns carry the whole model, and every surface is a view onto one of them.

Term	What it is
Project	A git repository you have opened. Carries a base branch, a trust decision, and its own notes.
Task	A prompt against a project. Moves through draft → running → review → merged.
Run	One agent's attempt at a task, in its own worktree on its own branch, with a live terminal and a stored transcript.
Fan-out	Dispatching one task to several agents at once. Each gets a branch, a worktree and a run.
Layout	A named set of agents raced in one pick — `duel`, `triad`, `swarm`, or your own.

Status versus activity

Two independent signals, and confusing them is the most common early mistake. Status is the process lifecycle: queued, running, succeeded, failed, cancelled. Activity is what the agent is doing right now — working, blocked, done, idle — classified from its output. A run can be running and blocked at the same time, and that combination is the one worth looking for: it means the agent is waiting on you.

Configuration

Two files, with deliberately different authority. settings.json is yours; asylum.toml belongs to the repository.

settings.json

Your preferences: default agents, worktree directory, keybindings, theme, the loopback servers, and the list of plugins you have enabled. Lives in your config directory, is watched for changes, and reloads live. A bad value becomes a friendly diagnostic plus the default — it never aborts the load.

asylum.toml

Committed at the repository root, for defaults a project's collaborators should share.

base_branch = "main"
default_agents = ["claude-code", "codex"]
setup = ["bun install"]

[env]
RUST_BACKTRACE = "1"

Repository trust

Two of those fields execute. setup runs in a login shell with your full privileges every time a worktree is created, and [env] is injected into every agent process — where an entry like PATH or NODE_OPTIONS is code execution under another name. The file ships inside the repository, so for any repo you did not write, both are authored by someone else.

Opening a repository is not consent to run it. Until you trust a project, its setup commands and [env] overrides are withheld. The rest of the file still applies — base_branch and default_agents run nothing.

The readiness panel shows the position and offers Trust. Confirming restates the exact commands and environment entries you are authorising, because "do you trust this project?" is not a question anyone can answer without seeing them.

Trust is per-repository and revocable from the same panel. Revoking applies to the next worktree or run rather than retroactively — nothing can un-run a command that already ran. Withheld commands are recorded in the setup transcript, so a run that skipped them says so instead of failing later with a confusing missing dependency.

Checks are gated the same way: they run commands the repository declares for itself, like its own package.json scripts or Cargo entry points. Projects added before trust existed start untrusted — having opened a repository is not evidence that what it executes was reviewed.

The CLI

The installed binary is asylum. A local cargo run -p app stays asylumdev, so a development build never collides with an installed release.

Command	What it does
`asylum worktree create\|list\|remove`	Manage worktrees directly, without the GUI.
`asylum run <agent> <prompt>`	Start a single run from the terminal.
`asylum agent add\|list\|show\|remember\|forget\|rm`	Persistent named agents and what each one has learned about this repository.
`asylum schedule add\|list\|enable\|disable\|rm`	Run a task on a cadence, with nobody watching.
`asylum routine record\|run\|list\|show\|rm`	Record a workflow in an instrumented shell, then replay it.
`asylum layout list\|show`	Inspect the named agent presets available to this project.
`asylum search <query>`	Search across worktrees, notes, tasks and run transcripts.
`asylum control <verb>`	The agent control surface — `status`, `read`, `spawn`, `activity`, `check`, `remember`, `skill`.
`asylum wait run <id>`	Block until a run reaches a status or activity, or a timeout elapses.
`asylum keep set\|rm\|list`	The encrypted, project-scoped credential store.
`asylum call`	Spend a stored credential through the masked proxy, so an agent uses a key it never sees.
`asylum mcp list\|serve\|stdio`	The aggregated MCP gateway.
`asylum plugin install\|search\|list`	Install plugins from GitHub and discover them by topic.
`asylum snapshot\|click\|fill`	Computer-use automation against the desktop.

Named agents

A run is a thing that happened. A named agent is somebody who keeps happening: a name, a brief, and a growing list of what it has learned about this repository, put in front of every prompt it gets.

The memory is the point. Without it, every fresh run rediscovers that the integration tests need a database up, that the generated files are not the ones to edit, and that one test is flaky — and then the run ends and it is rediscovered again tomorrow. You add to it with asylum agent remember; a running agent adds to it itself with asylum control remember, as it works.

Command	What it does
`asylum agent add Reviewer --role '…'`	Hire one. `--agent` picks which CLI drives it. Re-running `add` updates the brief and keeps the memory.
`asylum agent list`	The roster, most recently used first, with how much each one knows.
`asylum agent show Reviewer`	Its brief and everything it knows — exactly what gets prepended to its prompts.
`asylum agent remember Reviewer '…'`	Teach it something yourself. The same line twice is stored once.
`asylum agent forget Reviewer`	Wipe the memory, keep the agent — for when it learned something wrong.
`asylum agent rm Reviewer`	Remove it. Its past runs stay on the board.

Named agents are scoped to a project, because a role is about a codebase: "Reviewer" in a Rust workspace and "Reviewer" on a marketing site have nothing useful to say to each other. An agent may write only to its own memory — a sibling on the same task can read your transcript but not plant a line that outlives the task. In the app they appear as chips beside the raw agents, each carrying the number of things it knows.

Unattended work

asylum schedule runs a task on a cadence with nobody present. A scheduled run is an ordinary run in every way that matters afterwards: same worktrees, same board, same review, same notifications — the whole point is that you review it the way you review anything else. Missed periods are skipped rather than replayed, so a laptop closed over a weekend wakes to one run instead of every night at once.

asylum routine is the other half: show Asylum a workflow once and replay it thereafter. Recording instruments a shell rather than watching the screen, because what is worth replaying in a repository is the commands — and a command does not care where a window moved to.

The agent control surface

A running agent can orchestrate the fleet from inside its own worktree. It learns the API from a skill, and reaches it over a token-authenticated loopback service whose credentials are injected into that run's environment. An agent can spawn a helper run, read a sibling's work, run the project's checks, report its own semantic state, and block until another run reaches a state it cares about.

This is what makes agent-driven sub-fleets possible: one agent plans, then dispatches and waits on the specialists. Lesson 12 of the course works through it end to end.

Secrets

asylum keep stores a credential encrypted and scoped to a project. asylum call spends it: the request goes through a local masked proxy that attaches the key upstream, so the agent gets the response without ever holding the secret. Both bind to loopback only and require a token — loopback is not an authentication boundary.

The MCP gateway

Rather than configuring every MCP server into every agent, Asylum runs one aggregating gateway. It fronts each configured upstream under its own namespace (<service>__<tool>), so an agent connects once and sees everything it is allowed to see.

Credentials are scoped: a gateway token names the caller's project — which decides which servers it can reach — and its run, so every tool call is attributable in the event log. The gateway is loopback-only, token-required, rate-limited, and refuses to start on a non-loopback bind.

Plugins

A plugin is a directory with a plugin.toml, contributing commands, a panel, event triggers, and MCP tools that agents can call. There are two runtimes: a process runtime that speaks JSON over stdio, and a WASM runtime sandboxed with capability-gated host access and bounded fuel.

Everything is disabled until you enable it. A plugin that is not enabled is inert — its triggers never fire and its commands never run. Enabling a process runtime is fully trusted, so it routes through a confirmation that restates the exact command, its authority, and the commit the code is installed at.

asylum plugin search           # discover by topic
asylum plugin install owner/repo
asylum plugin list

Integrations

Browse GitHub pull requests and issues without leaving the window, turn an issue straight into a worktree, and open a pull request from a finished run. Linear issues work the same way with a token configured.

The mobile companion

An opt-in HTTP server exposing projects, tasks, runs and notifications, plus an event stream so a phone can follow the fleet without polling. It is off by default and requires a token once enabled. Use it to watch a long fan-out from elsewhere and send a follow-up into a live run.