Documentation

Install

Download Asylum.dmg from GitHub releases, open it, and drag Asylum to Applications. Asylum needs macOS 11 or later and a Chromium-family browser — Chrome, Edge, Chromium, or Brave — for the Agents' computer.

With Automatic updates on (the default), Asylum checks GitHub for new releases and tells you when one is out. If a newer release exists and your build is more than 14 days old, it asks you to update before continuing. Turn Automatic updates off to skip both.

Build from source

You need Rust stable 1.96 or later and Xcode's command-line tools.

git clone https://github.com/wess/asylum && cd asylum
cargo run -p app            # dev build: the binary is asylumdev
cargo test --workspace      # all tests
scripts/bundle.sh           # release build + dist/Asylum.app
scripts/dmg.sh              # dist/Asylum.dmg

The dev binary is named asylumdev so it never collides with an installed asylum. To sign and notarize a release, see the FAQ.

Concepts

Agent

An AI agent with a name, a label, an avatar, a description (its lasting rules), memory, skills, routines, secrets, and optionally its own model.

Chat

Each Agent has one direct conversation with you. Group chats hold 2–6 Agents. Any message can start a thread.

Computer

One machine every Agent shares: a workspace folder, a sandboxed shell, a terminal, and a Chromium browser with a screen per Agent.

Card

Something in the conversation you can act on: an approval, a takeover, a secret request, a form, a draft, a routine.

Routine

Work an Agent does on its own — on a schedule, an interval, a webhook, or an app event.

Skill

A saved, reusable procedure. Agents write them, you teach them, or they come with a template.

Connector

An MCP server that gives Agents tools in another product: GitHub, Linear, Notion and so on.

Team Agent

An Agent you set up once and publish so teammates can add it, with team memory and optional Slack.

Agent and team presets

Press ⌘N and choose Agent presets or Team presets. Select a preset to preview its instructions and, for a team, its members. Press Create Agent or Create team. All roles and instructions can be edited afterward; agents use your default provider unless you pin another one.

Create a Project Manager and ask it to build a team for a named codebase or app. Provide the codebase location and the goal. It can create project agents, put them in a group, assign tasks, and coordinate reviews. Claude Code and Codex managers connect through Asylum's local MCP bridge. The manager can discover connected providers and choose a different provider and model for each member. Creating a team saves its agents and group together; ticket work starts only when delegated.

For ticket-driven development, ask: “Create a dev team for Morpheous using tickets assigned to Wesley Cope in the current sprint.” The manager loads its Jira project delivery skill to resolve the project, assignee, and sprint, read the tickets, and build a task plan. It passes ticket requirements and repository instructions to its team. Connect Jira in the Marketplace and provide the repository path if it cannot be established from the tickets. Jira assignees and statuses stay unchanged unless you authorize updates.

Agent roles: Project Manager, Chief of Staff, Talent Scout, Inbox Triage, Bug Reproducer, Expense Manager, Researcher, Planner, Coder, Reviewer, Writer, Editor, and Analyst.

A team preset creates fresh agents with individual conversations and a shared group chat. The group description contains their workflow. Creation respects the roster limit and saves the whole team together. Use Custom to create a blank agent, create a shared Team Agent, or group agents you already have.

Providers

A provider is a profile in Settings → Providers: either an HTTP endpoint that speaks the OpenAI chat-completions API, or a coding-agent CLI fed the conversation on stdin. Choose a provider from the list below. No provider is required in advance, and no xAI account is needed for chat:

Refresh models asks an HTTP provider for its /models. One provider is the default for new Agents; a fast provider and model handle background work — Auto-review, memory summaries, names — and fall back to the default.

Requests that fail before any text arrives (a connection error, 408, 429, or 5xx) are retried with jittered backoff, three times by default (retries). A reply that has started streaming is never retried.

Per-Agent models

Every Agent can pin its own provider and model in Agent settings → Model. Unpinned Agents follow the default. Pinned Agents are told which model they are, and the pin survives changes to the default — so in one group chat, your researcher can be Opus through Anthropic, your writer GPT through LiteLLM, and your coder a local Qwen.

asylumdev pin Researcher anthropic claude-opus-4
asylumdev pin Coder ollama qwen3-coder:30b

LiteLLM

Point one profile at a LiteLLM proxy and every model behind it is available. Add the LiteLLM proxy preset and change the endpoint to your gateway (https://litellm.acme.dev/v1, or http://127.0.0.1:4000/v1 for a local proxy).

The key

Paste it into the profile's key field and press Save key. Asylum checks it against the gateway first, so a refused key is refused now rather than at an Agent's first turn, then keeps it in the Keychain. An exported LITELLM_API_KEY still wins over the saved key, so a shell or a CI job can override it.

Teams

Load teams lists the teams the key belongs to. Pick one and the model list follows the team's scope — a team limited to three models is offered three, not thirty. A key in no team (or a gateway without its database) sees the whole catalog. If the key itself is narrower than its team, Asylum says which models it can't call, because in a picker that just looks like a gateway with fewer models.

Reasoning, fallbacks, and checks

Reasoning

Off, Low, Medium, or High, sent as reasoning_effort with every request to that provider.

Use as fallback

Adds the provider to the fallback chain. When the active provider fails before saying anything, the next one in the chain answers, with its own default model or the same model name. A provider that has started answering is never replaced, so a reply is never duplicated. Only providers that call Asylum's tools stand in for each other.

Check provider

Sends a small, real (billed) request to the model. Listing models only proves the gateway answers; this proves the key, the model name, and the upstream provider all work.

asylumdev teams litellm              # the key's teams and their models
asylumdev check litellm claude-sonnet  # a real request through the gateway
asylumdev pin Researcher litellm claude-opus

CLI agents

The Claude Code and Codex presets run the installed, signed-in CLI headlessly in the workspace, feeding it the conversation on stdin and turning its final answer (or Claude's stream-json events) into the Agent's reply. Asylum automatically supplies a temporary local MCP connection for these presets. It exposes Asylum tools and connected apps, including real agent creation, team creation and handoffs. Asylum tool calls use the same approval checks and chat cards as HTTP providers. The connection is authenticated, bound to the current Agent and turn, and closed afterward. The CLI retains its own coding tools and permission controls. Custom process profiles do not receive this bridge.

Credentials

Asylum never writes an API key to its settings file. The usual way is to paste it: in onboarding (Connect with an API key), in Add provider (the default, Paste a key), or in the key field on any provider's card. Asylum checks the key against the provider first and refuses one that doesn't work, then keeps it in the macOS Keychain. Pasting a key on a provider set up another way switches it to the pasted key.

A profile's credential is one of:

Keychain

A pasted key, kept in the macOS Keychain. The default.

Environment

The name of an environment variable, for keys you already export in your shell. If the variable isn't set, a key pasted for that provider is used instead.

Synapse

A secret name in Synapse, resolved into a variable.

None

For local servers that don't need one.

Agents

Create an Agent with ⌘N, from a template link, or from onboarding's gallery: Chief of Staff, Talent Scout, Inbox Triage, Bug Reproducer, Expense Manager, and Researcher. An Agent's description holds durable rules ("Never send external messages without approval"); messages hold the task at hand.

In the sidebar, Agents can be pinned, filed into sections, hidden, duplicated, renamed, or deleted. An Agent's status dot shows idle, working, waiting on you, or done. Deleting an Agent removes its conversation and routines; files on the computer and browser sign-ins stay.

Avatars are 16-bit sprites: pick a class — Warrior, Knight, Wizard, Healer, Thief, Monk, Ranger, or Sage — and its clothes, trim, hair, and skin colors. An Agent you never customize gets a sprite chosen from its id, the same everywhere. You can also generate an image from a description or upload one (under 25 MB).

Chat and composer

• Streaming replies with every tool call shown inline; expand one to see its input and output. Turn on Show reasoning to see a model's thinking.
• Attachments: drag, paste, or pick up to 6 files, 25 MB each (videos up to 200 MB). They're copied into the workspace.
• @ mentions an Agent; / picks a skill.
• Threads: reply to any message to keep side conversations out of the main flow.
• Reactions, Find (⌘F), drafts that survive switching chats, and Enter sends (or ⌘↩ with it off).
• A new message preempts the Agent's current reply in that chat; routine runs and handoffs queue behind it.
• ⌘. stops the Agent and drops its queue.

Cards

Groups and handoffs

Start a group chat from ⌘N → Custom by ticking 2 to 6 Agents. Messages go to the Agents you @mention, to everyone with @everyone, or — with no mention — to the Agent that makes sense to answer. Agents can hand work to another Agent or post into a group; the result comes back as a handoff card. To stop thank-you loops, a pair of Agents can hand off at most 3 times in 10 minutes without you saying something.

Memory

Agents remember facts, preferences, and summaries of past work, recalled into each conversation. Review and delete memories in the Agent's details. Turn memory off globally with Memory in settings. Team Agents keep team memory; when you turn a personal Agent into a Team Agent you pick which memories come along — facts and summaries by default, preferences stay private.

Skills

Skills are reusable procedures in one library, enabled per Agent. They come from four places: an Agent writes one when you ask it to save what worked; you teach one by demonstration; an Agent learns one from repeated work; or one is packaged with a template. Pick one with / in the composer, or let the Agent choose.

Teach a task

Click Teach a task in a chat's header and do the task in the Agent's browser. Asylum records clicks, typing, form submits, and pages — up to 10 minutes — with password fields stored as [secret]. Stop, and the Agent turns the recording into a skill you can edit.

Routines

Ask an Agent to do something regularly and it creates a routine. Each Agent can hold up to 50; each keeps its last 20 runs.

curl -X POST http://127.0.0.1:47821/routines/<routine-id> \
  -H "Authorization: Bearer <routine-key>" \
  -H "Content-Type: application/json" \
  -d '{"event": "issue.opened", "title": "Checkout fails on Safari"}'

The JSON body is handed to the run with the routine's instruction. 200 means a run started; 401 a wrong key; 409 a paused routine. The server listens on 127.0.0.1 only — expose it with a tunnel if a service outside your Mac needs to reach it.

Routines run while Asylum is running (the window can be closed). If you haven't opened Asylum in a week, it asks whether to keep routines running and pauses them a day later if you don't answer.

Connectors

The Marketplace (⌘⇧M) lists MCP servers Agents can use:

GitHubLinearNotionJira & ConfluenceJira & Confluence (API token)SentryStripeSupabaseVercelHugging FaceDeepWikiContext7Google WorkspaceSlackPagerDutyBrave SearchPostgresPlaywrightDatadogSalesforceFigma

Remote servers sign in through your browser with OAuth (discovery, dynamic registration, PKCE, refresh) or take a pasted token; local servers run as a command with the fields they need. Connectors can hold several labeled accounts, and each tool can be switched off. Custom MCP server adds any HTTPS URL or local command. Tools appear to Agents as <connector>__<tool>; read-only tools run freely, the rest go through approvals.

Jira and Confluence

There are two ways in, and the Jira skills work with either:

For the API-token connector, create a token at id.atlassian.com → Security → API tokens, then enter your site URL (https://acme.atlassian.net), your account email, and the token. Confluence fields are optional. Asylum checks the credentials against Jira before saving them. It needs uv (brew install uv).

Reading issues runs freely; creating, editing, transitioning, commenting, and deleting go through approvals. The Marketplace's Skills tab has eight Jira skills, each marked with whether a Jira connector is connected:

Every skill proposes changes and asks before writing to Jira. Pair them with routines — "every weekday at 9:00, run /Jira standup for SHOP" — and they run on their own.

Templates

Create template (Agent details → Share) packages an Agent's name, avatar, description, skills, and routines — never secrets, memories, or files — into an asylum://template/… link, public or team-only. Opening a link shows what it contains and any warnings, and asks you to accept the third-party Agent terms before adding it. Strip API keys, internal URLs, and customer data from descriptions before sharing.

Team Agents

Create one from ⌘N → Create new Team Agent, or convert a personal Agent with Publish to Team (copy it, or start fresh). A Team Agent's setup covers connectors, secrets, reference files (.txt .md .csv .json .yaml, up to 256,000 characters each), and skills. It needs a name and a description of at most 140 characters before it can be published. Teammates add it with its team link and run it on their own Mac.

Team Agent secrets have their own limits: 100 per Agent, 32 KB each, 96 KB in total.

Slack

Optional. A published Team Agent can get its own Slack app: Bring to your team's Slack in its Share tab.

1. Create Slack app opens Slack with a generated manifest (bot user, scopes, events, Socket Mode). Install it to your workspace.
2. Paste the Bot User OAuth Token (xoxb-…) and an app-level token with connections:write (xapp-…), then Connect.
3. Invite it to channels with /invite.

It connects over Socket Mode, so nothing on your Mac is exposed to the internet. It answers every DM; in channels and group DMs it answers when mentioned and then follows that thread. It ignores other bots. If you list linked Slack accounts in Settings → Team Setup, only those teammates get answers — others are asked, privately, to link. If your workspace needs admin approval for apps, choose My workspace needs admin approval to track it.

Voice

Off by default. Turn on Settings → General → Voice features to get dictation (⌘D — tap to toggle, hold to talk), live voice chat with an Agent (barge-in, transcripts, mute, follow-up work after the call), and voice memos. Voice uses xAI's speech and realtime APIs and needs an xAI key, whatever your chat provider. Voice, speed, and language can be changed during a call.

The workspace panel contains your built-in Browser and Terminal, plus the Agent screen and files. Use the title-bar buttons or ⌘⇧B and ⌘⇧T. It opens at the bottom by default; use its dock controls or Settings → General → Workspace panel to move it left or right. Drag the divider to resize, or maximize and hide the panel. Your browser page and terminal session survive switching chats and hiding the panel. The terminal is your local shell, starts in the shared workspace, and accepts your own commands, including changing directories to a repository and running Git.

The computer

All Agents share one computer, kept in Asylum's data folder:

Workspace

The shared filesystem. Agents read and write files here; you browse it in the Files tab.

Shell

With Isolate the computer on (the default), commands run under a macOS sandbox-exec profile that allows writes only to the workspace, temp folders, and tool caches. Output is clipped and secret values are redacted.

Terminal

A real terminal in the workspace, embedded with libsinclair.

Browser

A Chromium profile shared by every Agent, so sign-ins carry over, with one page — a screen — per Agent.

Open the panel with ⌘⇧O. It keeps working with the window closed.

Built-in browser

Press ⌘⇧B (or click a link card) to open a web page in the workspace panel: back, forward, reload, an address bar that takes URLs or searches, and a button to open the page in your default browser (⌘-click a link to go straight there). Clicking an HTML page, image, PDF, or text file in the computer's Files tab previews it here. This is your browser — the Agents keep their own on the computer, where sign-ins are shared between them.

The Agents' browser

Agents see pages as numbered elements and act on them: open, look, click, type, press keys, scroll, go back, screenshot. The Screen tab shows the selected Agent's page live. Network Controls, if your admin sets them, apply to every page and redirect.

Takeover

When an Agent can't go on — a login, a captcha, a payment form — it asks you to take over. You click, type, and scroll in the panel (or full-window), then press I'm done and the Agent carries on. For passkeys and hardware security keys choose Open in a window: the browser relaunches visibly so macOS can show its own prompt, and returns to headless afterwards.

Maintenance

In Settings → Computer:

With Hibernate when idle on, the browser stops after 30 idle minutes and wakes on next use. Asylum warns when free disk drops under 5 GB and again under 1 GB; Disk Saver has an Agent audit what's taking space.

Approvals

Every tool call is classed before it runs:

Free

Reading, looking, searching — runs without asking.

Review

Changes that are easy to undo — checked by Auto-review if it's on.

Consequential

Sending, posting, paying, deleting, publishing — asks unless a rule or Auto-review allows it.

Local

Anything on your own Mac outside the computer — see local execution.

Connector tools whose names start with get, list, search, read, fetch, find, query, view, lookup, describe, or ask are treated as reads. Approvals requested by routines or handoffs (with nobody watching) expire after 10 minutes and the Agent reports what it skipped.

Auto-review and rules

With Auto-review on, a fast model reads each non-free action, the request it serves, and your rules, and either proceeds, denies with a reason, or asks you. Rules are plain sentences of two kinds — Ask first and Allow automatically — and Ask first wins a conflict. Always allow on a card saves an Allow rule. Rules an admin sets are locked.

Local execution

Execution on Local Computer controls whether Agents may run commands or read files on your Mac itself, outside their computer: Ask (default; the card offers Always allow / Allow once / Never / Deny once), Always, or Never. An admin can set a stricter ceiling.

Secrets

Per-Agent secrets have a name in capitals (API_TOKEN) and a description; the value is stored in the macOS Keychain and never shown again. When an Agent runs a command the value is injected as that environment variable and redacted from the output. An Agent can also fill a secret into a page field without reading it. Limits: 25 per Agent, 8 to 4,096 bytes each (Team Agents: 100, up to 32 KB, 96 KB total). Names the computer sets — PATH, HOME, proxy variables, anything starting ASYLUM_ — are reserved.

Security

• Everything runs on your Mac. Conversations, memories, and settings stay in Asylum's data folder; the only outbound traffic is to the model providers, connectors, and sites you choose.
• Agents within one Mac share a computer; they are not isolated from each other. Use separate macOS users for separation.
• Web pages and tool results are marked untrusted to the model. Approvals are the boundary that matters: keep Auto-review on and add Ask-first rules for anything you care about.
• Keys and secrets live in the Keychain, never in agents.json.
• The routine webhook and Admin API listen on 127.0.0.1 only and need a key or token.
• Report vulnerabilities privately through GitHub security advisories.

Activity

Settings → Activity has a week of Insights (conversations, messages, actions, what approvals stopped, top tools and Agents), the Action Recording log (tool, target, outcome — never arguments or results — kept 90 days), the audit log of settings, rules, connectors, policy, and computer changes, and export. Export one conversation from its sidebar menu, or all of them as JSON plus Markdown with prompts, responses, and tool input and output. OpenTelemetry and the Admin API are covered in the admin guide.

Sync

Turn on Sync sections across your Macs and sections, which Agents are in them, and pins sync through a folder in iCloud Drive. Agents are matched by name across Macs.

Usage

Settings → Usage shows tokens used this week, by Agent, against an optional weekly limit (resets Mondays). With Keep going on, Agents continue past it up to a monthly allowance; a running Agent always finishes its turn. Nothing is charged — the limits only cap spend on your own provider accounts.

Built-in tools

Settings file

Settings live in ~/.config/asylum/agents.json (JSON with comments). The app writes it; you can edit it too — changes are picked up live, unknown keys are reported, and a bad value falls back to its default rather than stopping the app.

Shortcuts

Command line

The app binary also runs without a window. In a release, it's /Applications/Asylum.app/Contents/MacOS/asylum; from source, target/debug/asylumdev.

Environment: ASYLUM_TRACE=<file> logs each model exchange; ASYLUM_POLICY=<file> points at a policy file other than the system one.

Paths

Languages

31 interface languages: English, Afrikaans, Arabic, Bengali, Chinese (Simplified and Traditional), Czech, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Norwegian Bokmål, Polish, Portuguese, Russian, Swedish, Thai, Turkish, Ukrainian, Urdu, and Vietnamese. Choose one in Settings → General, or follow the system. Translations improve with your help — see crates/app/i18n/ in the repository.

Troubleshooting

"Couldn't reach the computer"

Press Retry, then Recover computer. Make sure a Chromium-family browser is installed. A previous crash can leave a browser holding the profile; Asylum reclaims it on the next start.

An Agent says to pick a model

The provider has no default model. Open Settings → Providers, refresh models, pick one.

LiteLLM returns 401

The key variable isn't set in the environment Asylum was launched from. Launching from Finder doesn't read your shell profile; set it with launchctl setenv LITELLM_API_KEY … or use a Keychain credential.

Ollama replies are empty

Some models think and then stop. Asylum nudges a model that returned only reasoning once; if it persists, try a different model or turn on Show reasoning to see what happened.

A routine didn't run

Check it's active, that Background work is on, and its run history in Agent details → Tasks. Routines run only while Asylum is running.

A local connector won't start

Local connectors run with npx or uvx. Install Node or uv; Asylum uses your login shell's PATH, so anything on it is found even when Asylum is opened from Finder.

Jira says it rejected the credentials

Use your Atlassian account email and an API token (not your password), and the site URL without a path, e.g. https://acme.atlassian.net.

A connector says sign in again

Its OAuth token expired and couldn't refresh. Use the Connect card or the Marketplace.

"Blocked by your admin's network policy"

Network Controls are on. Ask your admin to allow the site.

FAQ

Is it free?

Yes. Asylum is open source under the Apache 2.0 license, with no account, subscription, or telemetry. You pay only your model providers, if any.

Does it work offline?

With a local model through Ollama, chat and the computer work without internet; web tools and connectors obviously don't.

Windows or Linux?

Not yet. Asylum is macOS-only for now.

Who makes Asylum?

It's an independent open-source project. It isn't affiliated with any model provider; xAI, OpenAI, Anthropic and the rest are simply providers you can choose.

How do I sign and notarize a release?

xcrun notarytool store-credentials asylum \
  --apple-id <apple-id> --team-id <TEAMID> --password <app-specific-password>
export CODESIGN_IDENTITY="Developer ID Application: <Name> (<TEAMID>)"
export NOTARY_PROFILE=asylum
scripts/bundle.sh && scripts/dmg.sh

Where's the architecture documented?

In CLAUDE.md, with the feature list in docs/features.md.