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

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

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.