All docs
System
Architecture
Composition, the split between Desk and Daemon, where plugins and data live, connection and authorization, disconnects and restarts.
Composition
There is one executable per platform (Windows x64, Linux x64), ail, compiled to a single file; the target machine needs no extra runtime. It has three uses:
| Use | What it is | Where it runs |
|---|---|---|
ail desk |
Agent Desk | One machine of your choice, one per person |
ail daemon |
Client Daemon | One per Client |
| Other subcommands | The command line | Every Client |
The main path is: browser ↔ Desk (HTTP and WebSocket) ↔ Daemon (WebSocket) ↔ adapter process (ACP over standard input and output) ↔ harness.
The split between Desk and Daemon
| Desk | Daemon |
|---|---|
| Host of the UI | The outbound long-lived connection to the Desk |
| Database | Hosting Workers |
| The engine: hand-offs, queues, wake-ups, the Router contract, reports | Non-interactive shell and interactive consoles |
| Authentication and authorization | Everything in the local plugin directory: checkouts, sync, worktrees, closing actions |
| Report files | Building UI plugins |
- The Daemon dials the Desk. A Client may sit behind NAT or be offline; the Desk's address is fixed.
- The Desk checks out no repositories. Plugins live in the plugin directory of some Client; when the Desk needs their content it asks that Client's Daemon. The Desk's machine therefore needs neither Git nor repository credentials.
- The engine is in the Desk; actions on repositories are in the Daemon. Everything the engine does to a repository is a named request to that Daemon, answered with a structured result. The engine never assembles shell text.
- The Daemon has no business state of its own. It keeps only its connection credential and the archive used to reconnect sessions.
Where plugins live
Each Client's Daemon is given a plugin directory at start-up. The directory is flat:
<plugin directory>/
main/ the main repository
official/ the official plugin
<repo id>/ one directory per other Repo
.worktrees/<name>/<repo id>/ task worktrees
.scratch/<run id>/ scratch directory of a run
The Client that holds the main repository and the official plugin is called the main Client; roles, workflows and the UI take effect there as soon as they are changed, without a push. A Repo is checked out on one Client, the main Client by default, and can be placed on another. The formats are in Plugins.
Where data lives
| Data | Source of truth |
|---|---|
| Repo registrations, roles, workflows, harness definitions, UI source, the Journal | Files in Git |
| Working copies, worktrees, task records | Each Repo's Git repository |
| Clients, pairings, authorization rules | The Desk database |
| Sessions, turns, queued messages, runs and their logs, reports and answers | The Desk database |
| Harness login credentials | The harness itself. aiL neither reads nor writes them |
The database is the built-in SQLite. Conversation history on a page comes only from it and is never replayed from a harness.
Connection, ownership and authorization
- Pairing. The Desk issues a one-time pairing code, bound to a Client id and with an expiry. The Client registers with it and receives its own credential and the Desk's public-key identity.
- Connection. The Daemon opens a WebSocket to the Desk. The handshake is mutual: the Desk first signs a challenge with its Ed25519 private key, and only after the Daemon has verified that this is the Desk it paired with does it present its credential. Both sides watch the heartbeat; after 15 seconds without one the connection is closed and the Daemon reconnects with back-off.
- Ownership. A Client belongs to exactly one Desk, and no other Desk can control it.
- Principals. Three kinds of principal send requests to the Desk: the owner (requests without a credential),
client:<id>(with a Client credential) andsession:<id>(with a session token). - Authorization. Rules are held centrally in the Desk, deny by default, and written per Client: which Client may do what to which target Clients. There are three actions:
powershell,bashandsession. A refused request returnsAUTHZ_DENIEDand names the principal, the target and the action.
The Desk has no login: a request without a credential is the owner. It should listen only on a private network of your own (for example a Tailscale tailnet) and never be exposed to the public internet.
aiL is not designed to resist attack: the user is you. What the above guarantees is that ownership is clear and authorization is not bypassed by accident.
Disconnects and restarts
A turn counts only while the Desk, the Daemon and the connection between them are all present. If any is missing the turn is recorded as failed and picked up afterwards:
| What happened | Result |
|---|---|
| The connection dropped (network, Daemon exit or upgrade) | Turns in progress on that Client are recorded as failed with DAEMON_DISCONNECTED. The Daemon ends the running adapter process and reconnects with back-off |
| The Desk restarted | On start-up, turns still marked in progress are recorded as failed with DESK_RESTARTED |
What the agent had already done in the failed turn is still there. When a workflow turn fails for either reason, the engine waits for that Client to reconnect and asks the Worker to continue from where it stopped, without disturbing anyone.
When a session has had no turn for 30 minutes, the Desk asks the Daemon to end its adapter process. The next message reconnects the same session with its context intact.