# Connections and runtimes

> Where ADF Studio runs agents (Local, the default, with every saved connection to another computer; Inside Studio, legacy), upgrading from 0.7.x and from remote mode, choosing the mode, what moves, quitting, Studio and the terminal app together, version mismatch, recovery, and every message these features show

Source: https://github.com/christianbalevski/adf/blob/v0.8.3/docs/guides/studio-backend.md (adf v0.8.3)

ADF Studio runs agents in one of two modes. You choose it in
**Settings → Connections** ([Connection](#connection)); Studio reads the choice
at launch, so a change applies at the next launch. In Local mode, Studio
also connects to every saved connection to another computer; adding or
removing one takes effect at once, without a restart.

| Mode | Agents run in | Typical use |
|---|---|---|
| **Local** | A background service on this computer, with the same settings file and agent files as Studio | The default. Studio and the terminal app (`adf`) show the same agents at the same time; with **Keep running after Studio quits** on, agents keep running when Studio is closed |
| **Inside Studio (legacy)** | Studio's own process | A fallback for this release only, if the background service does not work for you; the next release removes it. Agents stop when you quit Studio |

Agents on another computer (a server, a desktop) run in the background
service there. Each saved connection is a runtime of its own, listed with
the local runtime ([Remote computer](#remote-computer)). Inside Studio connects
to none of them.

The background service is the agent server (the ADF daemon, `adf daemon`).
Studio calls it a **server**: the **local server** on this computer, a
**remote server** on another computer. The rest of this guide says "server"
for what Studio shows and "daemon" where it names the CLI, its files or its
messages.

Without a `studio-backend.json` in Studio's user data folder, Studio runs
in Local mode and writes that choice into the file at its first launch, so a
later release reads an explicit choice. The file names the modes `local`
(Local) and `embedded` (Inside Studio); a file that says
`"mode": "embedded"` keeps Inside Studio. A file an earlier release wrote
with `"mode": "remote"` is migrated at the first launch ([Upgrading from
remote mode](#upgrading-from-remote-mode)). The file holds the mode,
`keepDaemonRunning`, the origins you confirmed plain http for, the order of
the other computers'
runtimes (`runtimeOrder`, written only once a connection is saved, so the
file of a Studio with the local runtime only is not rewritten), and one
connection without a fingerprint (its URL and token, encrypted with Electron's safeStorage: DPAPI
on Windows, the Keychain on macOS, the Secret Service on Linux). Saved
connections with a fingerprint are in `cli-remotes.json`
([Saved connections and adf](#saved-connections-and-adf)).

Inside Studio and the local runtime look and behave the same. A runtime on
another computer differs where the machine boundary forces it; [Remote
computer](#remote-computer) lists each difference.

## Connection

Settings has two groups (design:
[settings-scopes.md](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/settings-scopes.md)): **Studio**, the app on
this computer (Appearance, Connection, Notifications, Updates, Privacy,
About), and the runtime's pages (Prompts, Agent templates, Providers,
Packages, MCP servers, Skills, Channels, Files, Identity, Networking,
Compute, Usage). With the local runtime only, the runtime group has no heading.
With a connection saved, it is headed **Server** with a picker of the
server names ("*name* (Local)", "box-1", …); the runtime pages show the
server picked there, under a header strip "Server | *name*" with the server's
icon, and the Studio pages do not change. Settings opens on the server of the
open agent (from an agent window: that window's server), else the local
server; the choice is not saved. A picked server that is not connected is
listed with its state ("box-1 · Not connected, retrying"), and its pages show
"Not connected to *name*." with their controls disabled.

### Runtime names

Runtime names show only while a connection is saved. This computer's runtime
is *name* (Local), for example "laptop-1 (Local)": *name* is the runtime
alias (Settings → Identity), else the computer's name, and the runtime is
"Local" when neither is known. A runtime on another computer shows its saved
name with the remote icon (tooltip "Remote"). The same names are used in the
status bar, the sidebar, Go to Agent, the Mesh view, the bell, notifications,
agent window titles and the Help menu.

**Studio → Connections** has one **Add** at the top ([Add](#add)), then
three sections, from top to bottom (design:
[multi-runtime.md §6.5](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/multi-runtime.md#65-connections-page)):

1. **Local server** ("The agent server on this computer."): *name* (Local)
   ([Local server](#local-server)).
2. **Remote servers** ("Agent servers on other computers that this Studio
   connects to."): the saved connections ([Remote servers](#remote-servers)).
3. **Devices** ("Devices that can access *name* (Local)."): the other
   computers and Studios that use the local server ([Devices](#devices)).

Remote servers and Devices fold to their heading line while they hold
nothing; the heading keeps the count ("None", "2 servers") or the state
("Off", "On · 2 devices") in view, and a click opens them. Nothing is hidden
outright.

### Local server

The local server is always listed here, never under Remote servers:

| Row | State | Action |
|---|---|---|
| *name* (Local) | Connected (or Connecting, Not connected, retrying, Not connected); none while Inside Studio runs | None; **Connect** while Inside Studio runs |
| Inside Studio (legacy), only while it runs or is saved | Connected, or none | **Connect** |

**Details** under the name shows the pid, who started the server, its URL,
its version and the trust in its key ([Local server status](#local-server-status)).
**Inside Studio (legacy)** is in the local row's **More** menu (⋯) while it
is not a row. **Connect** on *name* (Local) (while Inside Studio runs) or on
Inside Studio (legacy) saves that mode for the next launch, and the page
shows "Next launch: *name*." with **Restart**. Nothing restarts until then
([Switch the backend](#switch-the-backend)).

In Local mode the section also holds **Keep running after Studio quits**
([Quit Studio](#quit-studio)), the one quit setting, and "Default changed"
after the upgrade from 0.7.x ([Upgrading from 0.7.x](#upgrading-from-07x)).

### Remote servers

Each saved connection is a row: the remote icon, its name, its state
(Connected, Connecting, Not connected, retrying, or Not connected), its
address and fingerprint, and "Not encrypted" for a plain-http address. With
none saved: "None. To add a server, click Add, then Connect." Servers found
on the network that are not saved are listed in **Add → Connect**
([Connect](#connect)), not on the page. A saved connection is connected
while it is saved: there is no Connect step and no restart. **Remove** is in
a saved row's **More** menu (⋯), which opens over the page: "Removes the
address and token from Studio and adf.", plus "Closes *N* agent windows."
when that server has agent windows open, and "Still listed on *name*; revoke
it there." **Remove** then closes those windows, disconnects and forgets the
connection.

A saved connection reads its token from the OS keychain when it connects. On
macOS the keychain may ask once whether ADF Studio may use a token `adf
pair` saved; answer that prompt (it can be behind other windows). If the
keychain does not give the token, that runtime is not connected and says
why: "The OS keychain did not give the token for *name*; allow ADF Studio to
use it, or pair again." The other runtimes connect as usual.

While Inside Studio runs, Studio connects to no other computer: the saved
connections are listed with no state, and connect at the next launch in
Local mode.

The status bar shows the runtime right of the version, grouped with its
mesh and Kill. With the local runtime only: nothing while it is connected, and
its state without a name while it is not ("Connecting"). With a connection saved: one group, the
runtime of the open agent, or the local runtime when no agent is open. The
group shows the runtime's name ([Runtime names](#runtime-names)), its
address in the tooltip, its state while it is not connected ("box-1 ·
Not connected, retrying"), its **Mesh** and its **Kill**. **Kill** stops the
agents and the mesh of that runtime only ("Stops all agents and mesh on
*name*"), stays enabled while that runtime's mesh runs, and is disabled while
that runtime is not connected. A click on the name opens Studio →
Connections.

The up arrow beside the group (tooltip "Servers") opens a list of every
server: the local server first, then the other computers in the order they
were added (`runtimeOrder` in `studio-backend.json`). Each row shows the
name, the state, **Mesh** and **Kill**. **Kill all** at the top ("Stops all
agents and the mesh on every server") stops every connected server at once;
its result names what it stopped ("Stopped 3 agents · Mesh off"), or "Partial
stop · Not reached: box-1" for a server that is not connected or did not
answer. The arrow is red while a runtime not shown is not connected. `↑`/`↓`
move between the buttons; `Esc` closes the list and returns to the arrow. An
agent window shows the group of its own runtime and no arrow.

While a runtime is not connected, its sidebar group and its agents are
greyed, its pending approvals cannot be answered, and its agent windows stay
open with the connection state. A runtime that fails shows a notification
and its state; only the local runtime opens a dialog when it fails. **Help**
names each runtime that is not connected ("box-1: not connected
(https://…), retrying"); **Reconnect** acts on it, and is a submenu of their
names when more than one is down. Reconnect on another computer whose
connection failed connects it again without restarting Studio: its agent
windows keep their unsaved text as recovery copies, close, and reopen once
it connects. Agent windows of another computer that were open at the last
quit reopen once that computer connects.

**File → Open Recent** lists the local runtime's agents, then each other
computer's agents under its name (`runtimeRecentFiles` in
`studio-client-settings.json`); choosing one opens it on that computer.
**Clear Menu** clears the lists shown.

### Saved connections and adf

Studio, `adf` and the terminal app keep one list: `cli-remotes.json` next to
Studio's settings file, with each token in the OS keychain (service `ADF`,
account `remote-token:<fingerprint>`). When the keychain refuses a token or
there is none, Studio shows **Keychain unavailable** ("The token can be
saved in a file only you can read.", **Save to file** / **Cancel**) and
`adf pair` the same line with `Save to file? [y/N]`; Save to file saves it in
`cli-remote-tokens.json` (readable by your user only), Cancel saves nothing. A computer paired
in Studio is in `adf remotes`. One saved with `adf pair` or `adf remotes
add`, also while Studio runs, is a row in Studio and connects at once;
`adf remotes forget` disconnects it and closes its agent windows. Remove in
Studio is `adf remotes forget`: the list is written first, and the token is
deleted only when no other saved name holds the same computer (`adf pair
<host> --as lab`). An entry of `cli-remotes.json` that is not a valid saved
remote is kept as it is by every change to the list, named by `adf remotes`
and in Settings → Connections, and removed with `adf remotes forget <name>`.
Open Recent and the Mesh view of a computer follow its fingerprint: when its
name is no longer saved and another name holds that computer, they move
there (unless that name has its own); otherwise they are removed. Studio
applies this when it sees the list change, or at the next launch. A connection without a fingerprint (a
daemon set up by hand, remote access off there) is kept in
`studio-backend.json` as before, one at a time, and is connected too.

### Add

**Add** is the one button on Settings → Connections. It opens one dialog,
titled **Add**. Its first step is two cards side by side, each with an icon:

| Card | Icon | Help line | Use |
|---|---|---|---|
| **Connect** | A computer, an arrow out to a server | "Connect to a remote agent server." | This Studio uses a remote server ([Connect](#connect)) |
| **Share** | Computers, arrows in to a server | "Share this server." ("Share *name* (Local)." while a connection is saved) | Other devices use the local server ([Share](#share)). Only in Local mode; otherwise disabled, with the reason in its tooltip |

**Back** returns to the two cards.

**Connect** shows everything on one form:

1. **Found**: the servers found on this network (mDNS) and on your
   tailnet, with their address, fingerprint and "Pairing open". Pick one,
   or type an **Address**: `https://…`, `http://127.0.0.1:<port>` (an SSH
   tunnel) or `http://100.x.y.z:7385` (a tailnet address). Any other
   `http://` address needs **Unencrypted** ticked ("This address uses
   http. Anyone on this network can read the code and the token."). With
   nothing found: "No server found yet. On the other computer, click Add,
   then Share."
2. **Code** and **Token**, side by side, both visible: "Enter a code or a
   token. To get a code, click Add, then Share, on the other computer." Enter
   one of them, not both, then **Connect**.
3. With a code, Studio asks the server for its name and fingerprint (no
   token is sent): "Check that *name* shows fingerprint *fingerprint*."
   Check it, then **Pair** sends the code.
4. With a token, **Connect** checks it against the address and saves the
   connection. A device token comes from **Share** → **Token** on the other
   computer or from `adf daemon devices add`.
5. If remote access is off there, or the server runs an older ADF, a code
   cannot pair. The dialog shows Studio's sentence for the cause, for
   example "*url* has remote access off. Turn it on there: Settings →
   Connections → Add → Share." or "*host* runs an older ADF. Update ADF
   there, then pair again." Only when the server answered with no
   fingerprint does it add "To connect without a fingerprint, enter a
   token." A token connection without a fingerprint shows "Saved without a
   fingerprint; identity not checked." and replaces the previous one
   without a fingerprint after the **Replace connection** dialog.
6. A code is 6 digits. Anything else shows "Enter the 6-digit code." under
   **Code**, and **Connect** stays disabled.
7. The connection is saved and connects: **Done**.

A server picked from the list must answer with the fingerprint it was
found with; otherwise "The server at *address* has a different
fingerprint (*fingerprint*). Studio sent nothing. Select the server in the
list again." A
computer already saved is paired again only after **Replace** ("*name* is
already saved; replace its address and token?"); **Cancel** sends nothing.

A token is checked against the computer before it is saved: the computer
must prove it issued that device token, without the token being sent
([remote-access.md §5.2.1](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/remote-access.md)). A saved
connection's address that now answers with another fingerprint, or cannot
prove it holds this computer's token, is refused before the token is sent.
A computer that runs an older ADF is refused: "*name* runs an older ADF;
update it."

## Upgrading from 0.7.x

Studio 0.7.x ran agents itself (Inside Studio). From this release on, every
install runs in Local mode, including an install that ran 0.7.x. The first
launch after the upgrade runs the handover of a launch that changes from
Inside Studio to Local (see [What moves](#what-moves-during-a-switch)):

1. Studio moves your client settings, ChatGPT and Grok sessions, app-level MCP
   sign-ins and the runtime identity into the daemon's stores, before it
   starts the daemon. Agent files, tracked folders, providers and every other
   setting stay where they are; the daemon uses the same settings file.
2. It saves `"mode": "local"` to `studio-backend.json`.
3. It starts the daemon, which starts the agents set to start automatically,
   from the same tracked folders as Studio did.
4. Once the window is open and Studio has connected to the daemon, one
   dialog says "Agents now run in a background service on this computer (the
   ADF daemon)." and lists what moved
   ("Moved: Client settings, Owner phrase, Runtime identity, ChatGPT session,
   MCP sign-ins."). **Open the Guide** opens this section. If Studio could not
   connect, the dialog says "… but Studio could not connect to it." and that no agent
   runs yet. The dialog appears once: if Studio quits or restarts before it
   was shown, the next launch shows it, together with what that launch moved
   and what is still not done. Settings → Connections keeps a **Default changed** row
   with the date and the version; its **Details** lists what moved.

The dialog also says, when it applies:

| Text | Meaning |
|---|---|
| "Not done yet, retried at the next start: …" | An item did not move; it stays where it was and Studio retries at each start. See [When a move is not done](#when-a-move-is-not-done) |
| "Stays in Studio: Runtime identity (…)" and "The daemon runs as its own runtime: …" | This computer has no keychain the daemon can read (Linux without a Secret Service). Agents made in Studio unlock in the daemon only with the owner phrase (`adf identity restore`) or after `adf identity trust-daemon`. Files the daemon stamps show as "recognized" in Studio's review |
| "macOS asks once whether the ADF daemon may read Studio's runtime key from the keychain." | macOS shows that question when the daemon first reads the key. Choose **Always Allow** |

A fresh install has nothing to move: no dialog appears.

If the daemon was signed in to another account before the upgrade
(`adf auth login`), the accounts dialog of [Two accounts](#two-accounts-the-conflict-dialog)
appears during the first launch, on the small "ADF Studio is starting" window.

Two cases stop the first launch from moving anything:

| Dialog | Meaning | What to do |
|---|---|---|
| "An older ADF daemon (adf *X.Y*, started by the npm CLI) is running and uses the same settings." (or "An ADF daemon that Studio cannot identify is running on port *N* …") | An `adf` installed from npm before this release runs a daemon on Studio's settings. Agents run inside Studio for this launch only: nothing moves, the default is not saved, and Studio does not start your agents set to start automatically, since that daemon may run them | Stop it with `adf daemon stop`, update the CLI (`npm i -g @agentdocumentformat/cli@latest`), then restart Studio. To run one agent in Studio before that, stop it in the daemon (`adf stop <name>`), then open it in Studio and press Start |
| "Studio cannot use its backend settings file." with **Run on This Computer (Recommended)** and **Run Inside Studio (Legacy)** | `studio-backend.json` could not be parsed (Studio moved it aside as `studio-backend.json.corrupt-*`) or names an unknown mode | Choose one. Studio saves it, then moves your sign-ins to that side |
| "Studio cannot use or replace its backend settings file." with **… for This Launch** | The file cannot be read (for example `EACCES`); the dialog names the path and the error | Fix its permissions or delete it, then restart Studio. Until then the choice applies to one launch, and no sign-in moves |

To keep running agents in Studio for this release, open **Settings →
Connections**, choose **Inside Studio (legacy)** in the local server row's
**More** menu (Local server), then **Restart**. The next launch moves your
sign-ins back into Studio. Do not use `ADF_STUDIO_BACKEND=embedded` for this;
it runs agents inside Studio for one launch without moving anything back.

To go back to 0.7.x, first choose Inside Studio as above, check that the summary
after the restart lists no pending item, quit Studio, stop the daemon
(`adf daemon stop`) and install 0.7.x. Installing 0.7.x without that switch
leaves the ChatGPT, Grok and MCP sign-ins with the daemon, and the theme,
recent files and fleet layout in `studio-client-settings.json`, where 0.7.x
does not read them: sign in again in 0.7.x. Agent files, providers and the
owner identity are not affected.

## Upgrading from remote mode

An earlier release ran agents on one other computer at a time
(`"mode": "remote"` in `studio-backend.json`, chosen with **Connect** and a
restart). This release has no remote mode: every saved connection is
connected while it is saved. At the first launch of this release on such an
install, before it connects to anything, Studio:

1. in `studio-client-settings.json`, moves that computer's Open Recent
   (`remoteRecentFiles`) to `runtimeRecentFiles`, its Mesh view groups,
   stewards and layout (`fleetGroups`, `fleetStewards`, `fleetMapState`) to
   `runtimeFleet`, and its saved agent windows (`agentWindows`) to its
   runtime, each with the fingerprint it was paired with;
2. writes `"mode": "local"` to `studio-backend.json`, removes `remote.name`,
   and writes `runtimeOrder` with the connection that was in use first, then
   the other saved connections in the order they were paired;
3. starts the local runtime's daemon, which starts the agents set to start
   automatically, as at any launch, and connects to every saved connection.

Agents on the other computer keep running there; nothing restarts them.
Once the window is open, one dialog says "*name* is in Settings →
Connections." Its agent windows reopen once it connects. If that connection
is no longer saved (`adf remotes forget`), the dialog says "*name* is no
longer saved; add it again in Settings → Connections." and Studio runs This
computer only.

If either file cannot be written, this launch runs the same way, Settings →
Connections says "studio-backend.json still says remote …", and the next
launch migrates it again. If `studio-client-settings.json` cannot be
written, `studio-backend.json` is not rewritten either; this launch moves
the client keys in memory and writes them with the next change to that
file. Until `studio-backend.json` is migrated, every save of it in that
launch (the runtime order, Settings → Connections) keeps `"mode": "remote"`
and `remote.name`. While `studio-backend.json` still says remote after the
client keys moved, `studio-client-settings.json` holds
`"remoteModeMigrated": true`: the next launch does not move the Mesh view
keys again, so the ones the local runtime wrote meanwhile stay the local runtime's.
Any launch that reads a `studio-backend.json` that does not say remote
removes it. A launch that cannot read `cli-remotes.json` moves the client
keys, leaves `studio-backend.json` for the first launch that can read it,
and Settings → Connections says "studio-backend.json still says remote; it
is migrated at the first launch that can read the saved connections." A
launch Inside Studio (`ADF_STUDIO_BACKEND=embedded`) leaves both files for
the next launch.
`ADF_STUDIO_BACKEND=remote` is read as `local`. An older Studio that reads
the migrated file runs the local runtime only; the connections stay saved in
`cli-remotes.json`.

## Before your daily-driver week

For the week of daily use on a pre-release build of this branch
(`0.8.0-daemon.N`). The checklist walked during that week is
[daemon-backend-user-testing.md](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/daemon-backend-user-testing.md).

1. **Only this branch's builds on the machine.** Quit the release Studio, or
   uninstall it, and stop the daemon of an `adf` installed from npm
   (`adf daemon stop`), then uninstall that package. Then check:
   - `adf daemon status` reports no daemon (exit code 3), or one whose version
     is this build's;
   - `<config>/adf/leases/hosts/` (Windows: `%LOCALAPPDATA%\adf\leases\hosts\`)
     holds no `<pid>.json` of a process that is not this build's Studio or
     daemon. Each file names its `kind`, `pid`, `version` and `settingsPath`.
     A runtime of another build there runs agents from the same files.
2. **After the first launch in Local mode**, confirm the daemon took over
   Studio's identity and can prove it is local:
   - `adf identity` shows the runtime as `studio (adopted)`. Anything else
     means agents made by Studio stay locked in the daemon.
   - `adf daemon status` has no `proof     unavailable` line. With that line,
     owner import and the stored-value reveal (Settings → Providers keys,
     Identity panel Reveal) refuse until the daemon restarts.
3. **No owner switch from the terminal during the week.** Do not run
   `adf identity import` with a phrase of another owner (the import that asks
   you to type "switch"), unless you restart Studio in Local mode right
   after it. Studio re-signs its runtime entry for the new owner only at a
   local-mode boot; until then, agents Studio made do not open in the daemon.
   An owner import in Studio itself does this at once.
4. **Watchdogs that look for Studio by process name do not see a dead
   Studio.** The daemon Studio starts is `ADF Studio.exe` (or `ADF Studio` on
   macOS) too, so a check for the process name passes while only the daemon
   runs. Check for the window, or for Studio's pid, instead.
5. **The way back**, in this order:
   1. Settings → Connections → Inside Studio (legacy) → **Connect**, then **Restart**.
   2. After the restart, check the handover summary: no item may be pending.
      A pending item means a credential is still with the daemon. Fix what it
      names and restart again before going on.
   3. Stop the daemon: `adf daemon stop`.
   4. Reinstall the release (v0.7.8).

   Do not use `ADF_STUDIO_BACKEND=embedded` as the way back. It runs agents
   inside Studio without running the handover, so credentials moved to the daemon
   stay there.

## Switch the backend

1. Open **Settings → Connections** and choose **Inside Studio (legacy)** in
   the local server row's **More** menu (Local server), or
   **Connect** on ***name* (Local)** while Inside Studio runs. A saved
   connection has no Connect: it is connected while it is saved
   ([Connection](#connection)).
2. Studio saves the mode. Nothing restarts and no agent stops. The page
   shows "Next launch: *name*." with **Restart**.
3. At the next launch (**Restart**, or quit and start Studio), Studio moves
   what belongs to that mode's side before it starts anything (see [What
   moves](#what-moves-during-a-switch)). If something moved or is not done, a
   summary dialog says "Agents now run *on B*." (or "Agents now run *on B*,
   but part of the handover is not done.") and lists each item with its
   outcome.

Choosing the mode this launch runs again keeps it: "Saved."

**Restart** quits Studio as any quit does ([Quit Studio](#quit-studio)): a
daemon Studio started stops with its agents, and their turns in flight stop
with it. Running agents are not carried across: the next launch starts the
agents set to start automatically, in Studio or in the daemon. An agent a
daemon that keeps running still runs cannot start in Studio ([Agents in two
runtimes](#agents-in-two-runtimes)).

If `ADF_STUDIO_BACKEND` is set in Studio's environment, it overrides the
saved mode; Settings → Connections shows "*Mode* because ADF_STUDIO_BACKEND
is set." (for example "Inside Studio (legacy) because ADF_STUDIO_BACKEND is
set.").

### Messages on the Connection page

| Message | Meaning |
|---|---|
| "Saved." | You chose the mode this launch already runs |
| "Next launch: *name*." with **Restart** | The mode is stored in `studio-backend.json` and differs from the one this launch runs; the next launch runs it |
| "The OS keychain did not give the token for *name*; …" | Allow ADF Studio in the keychain prompt, or pair again |
| "In use." | Remove on *name* (Local) |
| "Add it first." | Connect on a computer that is not saved |
| "Already connected." | Connect on a saved connection; it is connected while it is saved |
| "Remote mode is gone; use Add in Settings → Connections." | A `mode: remote` save; this release has no remote mode |
| "Saved *name*." | Add saved the connection (with a code or a token); it connects |
| "Could not save *path*." / "Could not save the backend settings." / "Could not read the backend settings." | `studio-backend.json` could not be written or read; check the user data folder |
| "studio-backend.json: …" / "studio-backend.json: ignored …" | The file has a problem or fields this Studio does not use; Studio says what it ignored |
| "studio-backend.json still says remote …" | The migration of an earlier release's remote mode could not be saved; see [Upgrading from remote mode](#upgrading-from-remote-mode) |

## What moves during a switch

Some state cannot be shared between Studio and the daemon, so it moves with
the backend. Studio performs each move at its next start, before it starts or
attaches to the daemon. Each move writes the destination, reads it back, then
deletes the source, so a crash in the middle leaves two copies, never none;
the next start finishes the move.

| State | Inside Studio → Local | Local → Inside Studio |
|---|---|---|
| Running agents | Stop when Studio quits; the daemon starts the ones set to start automatically | A daemon Studio started stops with its agents when Studio quits; Studio starts the ones set to start automatically, unless a daemon that keeps running still runs them |
| Client settings (theme, fonts, recent files, Mesh view layout, notifications, menu bar, update and spellcheck choices) | Moved from `adf-settings.json` into `studio-client-settings.json` | Moved back |
| Runtime identity | Studio's runtime key is written to the OS keychain (account `studio-runtime:<scope>`), so the daemon signs as the same runtime and your agents show as yours in review | The keychain copy is deleted |
| ChatGPT and Grok sessions | `<provider>/auth.json` moves to `<provider>/auth.daemon.json` | Moved back |
| App-level MCP sign-ins | Moved into the daemon's keychain entries. They stay in Studio when the keychain cannot be opened or is locked; agents keep their own sealed copies | Moved back into Studio's settings: the ones Studio moved and the ones signed in while in Local mode. Sign-ins the daemon had before the first switch stay with it. When that first switch did not read the daemon's keychain entries (Studio had nothing to put there, or the keychain was unavailable or locked) and a daemon had already run on these settings, only the ones Studio moved come back; sign in again in Studio for the others. When the keychain cannot be opened or is locked at the switch back, none move |
| Owner seed phrase | Mirrored into the keychain entry `ADF / owner-mnemonic` when it is not there | Nothing |
| Open agent and tabs | Reopened after the restart | Reopened after the restart |

Agent files, tracked folders, providers and every other setting stay where
they are: in Local mode the daemon uses Studio's settings file and
agent files. Nothing moves to or from another computer: a runtime on another
computer uses its own sign-ins, keys and identity, and Studio sends it none
of this computer's. See [§5.5](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/daemon-backend.md#55-remote-mode).

Rationale: sessions move instead of being copied because ChatGPT and MCP
refresh tokens rotate. A copy left behind stops working the first time the other side
refreshes it, which would sign you out after you switch back.

The record of what moved is `studio-handover.json` in Studio's user data
folder. Do not edit it.

### Two accounts: the conflict dialog

If Studio and the daemon are signed in to the same provider with different
accounts, Studio asks "Studio and the ADF daemon are signed in to ChatGPT with
different accounts." (or Grok). Choose **Keep *account* (Studio)** or **Keep
*account* (daemon)**.

The dialog opens during the start, before the main window, on a small "ADF
Studio is starting" window in front. The other account's session is signed out here and saved,
encrypted with the daemon's key, as `<provider>/auth.replaced.<time>.json` in
Studio's user data folder (the dialog names the folder, the summary the file).
Each account set aside has its own file: a later conflict over another account
never overwrites it, and setting the same account aside again replaces its
file. To use that account
in the daemon instead: stop the daemon and replace `auth.daemon.json` with it
(Windows PowerShell: `Move-Item -Force auth.replaced.<time>.json auth.daemon.json`
in that provider's folder; `auth.daemon.json` already exists, so a plain rename
fails). Studio deletes each `auth.replaced.*.json` 30 days after it was written
(at its next start), or as soon as its account signs in again on either side;
the log names each file it deleted.

The same account signed in on both sides independently (the daemon signed in
before your first switch) keeps both sessions, each on its side; no accounts
dialog appears (the summary dialog still lists the switch).

### When a move is not done

The summary dialog names each item that did not move, and Studio retries at
the next start. Common reasons:

| Summary text | What to do |
|---|---|
| "not moved back: the ADF daemon pid N (started by cli) still runs on these settings …" | Stop it (`adf daemon stop`) and restart Studio |
| "not moved: `studio-handover.json` cannot be read …" / "is not a handover record this Studio reads" | Fix or delete the file, then restart Studio. Until then sign-ins stay where they are |
| "`studio-handover.json` is missing, so Studio cannot tell its sign-ins from the daemon's own …" | Sign in again in Studio where needed |
| MCP sign-ins "stay in Studio (…)" / Runtime identity "not shared: …" | This computer has no keychain the daemon can read (Linux without a Secret Service). The daemon runs as its own runtime; files it stamps show as "recognized" in Studio's review |

A launch in a session-only backend (`ADF_STUDIO_BACKEND`, or "Run Inside
Studio for This Session") moves client settings only; sign-ins and the runtime
identity stay where the saved backend keeps them.

## Quit Studio

**Settings → Connections → Local server → Keep running after Studio quits**
(`keepDaemonRunning`, the local server only, default off). It is the one
quit setting: the "Background" switch and the "On quit" **Keep running**
button of earlier releases both wrote it. The row says what happens at quit,
in one sentence:

| Row says | When |
|---|---|
| "When you quit Studio, Studio stops the server and its agents." | Off, and Studio started the server |
| "When you quit Studio, the server and its agents keep running." | On |
| "The ADF CLI started this server. Studio does not stop it when you quit Studio." (or "A service started this server. …") | Off, and `adf daemon start` or a service started it |


| Setting | When you quit Studio | After a Studio crash |
|---|---|---|
| Off | Studio stops a daemon it started, as quitting stops agents in Inside Studio mode | The daemon stops 60 seconds later |
| On | The daemon keeps running your agents; manage it with the ADF CLI (`adf daemon stop`) | The daemon keeps running |

A change applies from then on, also to the crash case; the page header
shows **Saved**.

A daemon started with `adf daemon start` (or a service manager) is never
stopped by Studio, whatever the setting says. Settings → Connections shows who
started the daemon.

If another client (the terminal app, another Studio) is connected when Studio
would stop the daemon, the daemon keeps running until the last client
disconnects, then stops. The clients that stay connected are told so:

- Studio shows a notification: "The ADF daemon keeps running while 1 other
  client is connected, and stops when the last one closes. (*reason*)" (or
  "*N* other clients are connected").
- The terminal app shows a notice: "The daemon stays up because this app is
  connected: …"

A Studio that connects again in the meantime clears the pending stop.

A runtime on another computer: quitting Studio never stops its daemon.
Quitting ends Studio's sessions on every runtime at once; a computer that
does not answer is given 1.5 seconds, then its daemon expires the session.

When devices are connected to this computer, quitting asks first:
[Quit with devices connected](#quit-with-devices-connected).

## Studio and the terminal app together

In Local mode, and on each runtime of another computer, Studio, the
terminal app (`adf`) and other `adf` commands are clients of the same daemon.
Each sees the same agents:

- A chat sent from one appears live in the others, with streamed tokens in
  the agent you have open.
- Starting, stopping, state changes, config edits, timers and file edits in
  one show in the others within a second.
- An approval or question resolved in one clears in all of them.
- Two Studios on different computers with the same saved connection see the same state of it.

In Inside Studio mode the terminal app cannot connect: `adf` refuses to start a
daemon while a Studio that runs agents inside itself uses the same settings ("ADF Studio (pid N)
is running agents from the same settings file (…)"). See
[Troubleshooting › Studio at the same time](https://agentdocumentformat.org/cli/troubleshooting#studio-at-the-same-time).

### Changed elsewhere

When an agent, another client or the CLI changes a file, the document or the
config while you have unsaved edits to it, Studio keeps your text and shows a
strip over the editor: "*File* was changed by *the agent* while you were
editing. Your changes are not saved." The writer is "the agent", "the
terminal app", "another Studio window", "the CLI or another API client" (an
`adf` command or a script), or "another client (*name*)".

| Button | What happens |
|---|---|
| **Reload** | Shows their version; your unsaved text is discarded |
| **Keep mine** | Saves your version over theirs |

While the strip is up, Ctrl+S saves nothing and moves focus to Reload.
Closing the tab, closing the agent or switching agents asks first: "Discard
your unsaved changes to …? Someone else changed it while you were editing."
("them" for several files).
A tab without unsaved edits updates in place, as before.

If Studio quits or crashes while the strip is up, your version is kept in
`<userData>/recovered/<agent>-<hash>/<path>`. The next launch shows "Studio
kept your unsaved version of *agent/path* from the last session, which ended
while someone else's change was waiting for your answer." with **Show
folder** and **Dismiss**. Dismiss moves the copies to
`recovered/archive/<time>/` (kept 30 days, at most 50 dismissals).

The terminal app checks before it writes. If the file changed since you
opened it, it shows "Concurrent change: *file*" ("WARNING: *file* changed
while you were editing (their change: …). Writing replaces that version.")
with **Overwrite** and **Discard** ("Not written. Your edited copy is kept at
*path*"). If another write lands between that check and the save, it asks
"*File* was changed by … after you opened it. Overwrite replaces their
version with yours. Reload keeps theirs." with **Overwrite** and **Reload
theirs** (nothing is written; your edited copy is kept).

### Streaming in the terminal app

The terminal app opens a client session on the daemon. The agent whose chat
view is open streams tokens whatever its `umbilical.stream_deltas` setting
says; other agents update when their turns, tools and states change. An
older daemon, or one with another client API version, makes the terminal app
fall back to `/events` and say so once in its activity log: "Live events over
/events: … Token streaming follows each agent's umbilical.stream_deltas."

## Local server status

Three places show the local server (the daemon) Studio uses:

- **Settings → Connections → Local server** (in Local mode): the
  connection state beside *name* (Local) ("Connected", "Connecting", "Not
  connected, retrying", "Not connected"; "Key not trusted" while the owner
  does not trust the server's key); **Details** shows the PID, who started
  it ("this Studio", "Studio", "the ADF CLI", "a service"), the URL, the
  version and the key ("trusted by the owner", or "not trusted. To trust it,
  run adf identity trust-daemon."). Studio reads who started
  the daemon again whenever it reconnects, so a daemon restarted with
  `adf daemon restart` reads "started by the ADF CLI".
- **Help menu**: **Open Daemon Log** (the local runtime; if the OS cannot open the
  file, a dialog says "Could not open the daemon log." with the path and the
  reason). While the connection is
  down, a status line ("ADF daemon: connecting…", "ADF daemon: not connected
  (*url*), retrying", "ADF daemon: not connected") and **Reconnect to the ADF
  Daemon**; after a failed launch also **Run Inside Studio for This Session**.
- **`adf daemon status`** in a terminal: also `started by …`, and `proof
  unavailable: …` when the daemon runs without its local proof (below).

If the server could not protect its local proof file (`daemon-local-proof`,
Windows `icacls` failure), Settings → Connections → Local server says
"Studio cannot show stored values or import an identity. Fix the permissions
of the server's data folder. Then restart the server." **Details** shows
"Local proof: not available (*reason*)".

## When the daemon is not reachable

| What you see | Meaning | What to do |
|---|---|---|
| Task-bar progress and the line "Starting the ADF daemon…" | Studio is starting the daemon | Wait; Studio connects when it answers |
| The line "Waiting for the ADF daemon (pid N)…" and one notification "Waiting for the ADF daemon (pid N)… Studio connects when it answers." | Another daemon is starting or stopping on these settings | Wait |
| Dialog "Studio lost its connection to the ADF daemon." (**Reconnect Now**, **Open Daemon Log**, **Dismiss**) | The connection dropped for more than 3 seconds. Studio keeps reconnecting. The dialog is not shown again within 60 seconds | Check `adf daemon status`. If the daemon stopped, start it (`adf daemon start`) or restart Studio, which starts one. Studio reconnects by itself and notifies "Reconnected to the ADF daemon." |
| Dialog "Studio could not connect to an ADF daemon." with **Reconnect**, **Run Inside Studio for This Session** and **Open Daemon Log** | No daemon for this launch (see the table below) | Fix the cause (Settings → Connections works without a daemon), then **Reconnect**: it restarts Studio and tries the daemon again. **Run Inside Studio for This Session** restarts Studio running agents itself for this launch only; the saved mode stays. The Help menu offers both later (**Reconnect to the ADF Daemon**, **Run Inside Studio for This Session**) |
| An action fails with "Cannot reach daemon at *url*: …" | The call was made while disconnected. Nothing was done | Retry after the reconnect |
| A chat waiting for its answer ends after 15 seconds without the daemon | Studio stops waiting; the daemon may still run the turn | Reopen the agent after the reconnect |
| Dialog "Emergency stop did not reach the ADF daemon. … Agents may still be running." (after **Kill**) | The stop request failed | Run `adf daemon stop` in a terminal, or stop the agents once Studio reconnects |
| Dialog "Emergency stop was partial." | The daemon stopped some agents; the dialog names the rest | Stop them by hand |
| Notification "Studio could not reopen *agent* on the ADF daemon after reconnecting (…). Open it again." | The open agent could not be held again after a reconnect | Open it again |
| Notification "*agent* is locked again after the ADF daemon restarted. Open it again to enter its password." | The daemon restarted and forgot the file password | Open the agent and enter its password |

Studio never falls back to Inside Studio on its own. The reasons in "Studio could
not connect to an ADF daemon." include:

| Reason | Fix |
|---|---|
| "The ADF daemon exited during startup (code 1). Its log says: "Failed to start: port 7385 on 127.0.0.1 is already in use"." | Another program holds the daemon port. Stop it, or set `ADF_DAEMON_PORT` for Studio and the CLI |
| "The ADF daemon exited during startup (code N)." with another line from its log | **Open Daemon Log** |
| "The ADF daemon did not answer …/health within 90s." | Same |
| "A daemon is running on port N but Studio cannot authenticate to it (token from …)." | The daemon uses another token: unset `ADF_DAEMON_TOKEN`, or stop that daemon |
| "A daemon is running on port N but has no GET /version; it is an older ADF build." | Update the CLI (`npm i -g @agentdocumentformat/cli@latest`) and run `adf daemon restart` |
| "The ADF daemon running on this machine (pid N) uses *file*, not *file*." | A daemon on another settings file holds the port. Stop it, or run it on another port |
| "The running ADF daemon (version …) does not match this Studio (client API …)." | See [Version mismatch](#version-mismatch) |

## Version mismatch

Studio and a daemon talk through a client API with a version number. If a
daemon with another client API version runs on Studio's settings, Studio asks
before it touches it: "The running ADF daemon is version *X*; this Studio is
*Y*."

| Button | What happens |
|---|---|
| **Restart the Daemon with Studio's Version** | Stops that daemon and its agents, starts this Studio's daemon, which starts the agents set to autostart |
| **Run Inside Studio for This Session** | Studio restarts and runs agents inside itself for this launch only. The daemon, its agents and its sign-ins stay as they are; Studio does not start an agent the daemon runs, and nothing moves between them. The next launch uses the saved backend again |

When the daemon was started by the ADF CLI or a service, or other clients are
connected to it, the dialog names them and the restart button reads
**Restart It Anyway**; **Run Inside Studio for This Session** is then the default. A replacement daemon
keeps the original's "started by", so Studio's quit does not stop a daemon
the CLI started.

A daemon of another release with the same client API version attaches
without a question. Settings → Connections shows its version under **Local server** →
**Details**.

## Run agents inside Studio when the daemon does not work

Inside Studio is the legacy backend. It stays for this release only, as a fallback;
the next release removes it. There are two ways to run agents in Studio again:

- **Settings → Connections → Inside Studio (legacy) → Connect**, then
  **Restart**. At that launch sign-ins and the runtime identity move back
  (if a daemon still runs on these settings, they stay with it until you
  stop it). This is the persistent way back.
- **One session**: start Studio with `ADF_STUDIO_BACKEND=embedded`. Only
  client settings move; sign-ins and the runtime identity stay as the saved
  backend keeps them. Settings →
  Connections shows "Inside Studio (legacy) because ADF_STUDIO_BACKEND is
  set." The version-mismatch dialog's **Run Inside Studio for This Session**
  does the same for one launch.

In a session-only Inside Studio launch, an agent the daemon still runs cannot
start in Studio (see [Agents in two runtimes](#agents-in-two-runtimes)), and
ChatGPT, Grok and MCP sign-ins that live in the daemon are not available.

## Remote computer

Set the daemon up on the server first: [Remote daemon](https://agentdocumentformat.org/cli/remote-daemon).
Then, in **Settings → Connections**:

1. **Add → Connect**: pick the server when it is found on this network or
   the tailnet, or type its address, then the code or a token, both on
   the same form ([Add](#add), [Connect](#connect)). A token is a device token
   from **Share** → **Token** on the other computer ([Share](#share)) or
   `adf daemon devices add`, or the `ADF_DAEMON_TOKEN` of a daemon set up
   by hand. It is never shown again.
   The token is as powerful as the server's owner seed phrase: a token
   holder can run code as the daemon (an MCP server or adapter command, then
   agent start) and read the phrase from the server's keychain. Save it only
   on a computer you trust with the phrase. Rotation: [The token is as
   powerful as your seed phrase](https://agentdocumentformat.org/cli/remote-daemon#the-token-is-as-powerful-as-your-seed-phrase).
2. The connection is saved and connects at once; Studio does not restart.
   The server's agents are listed in their own sidebar group, and its
   runtime group joins the status bar ([Connection](#connection)).

Plain `http://` to a `100.64.0.0/10` address is accepted without the
confirmation because Tailscale uses that range. Internet providers use the
same range for carrier-grade NAT, so on a network you do not control the
address may not be your tailnet. Prefer `https://` through `tailscale serve`
and the MagicDNS name ([Option 4: tailscale serve](https://agentdocumentformat.org/cli/remote-daemon#option-4-tailscale-serve)).

### Connection problems

Each failure is one sentence that names the URL. A daemon that cannot be
reached at launch is retried with growing pauses (2 s up to 30 s), with the
line "Waiting for the remote ADF daemon at *url* …" in Settings → Connections and
the Help menu and one notification ("*name*: Waiting for the remote ADF
daemon at *url*. Studio keeps trying."). The other failures are not retried:
the connection is not connected, with a notification of the sentence and
its state in Settings → Connections, the sidebar and the status bar; **Help
→ Reconnect** connects it again without a restart:

| Sentence starts with | Fix |
|---|---|
| "Cannot reach the agent server at …" / "… did not answer within 15 s" | The server, tunnel or tailnet is down. Studio keeps trying |
| "… answered HTTP 502/503/504: a proxy answers there, but the agent server behind it does not." | Start the server there (`adf daemon start`). Studio keeps trying |
| "The agent server at … refused the token. On *host*, click Add, then Share, and pair again." | On the host, **Add → Share**, and pair again. The master token (`adf daemon token`) is refused from other computers. A token refused after connecting ends the connection with the same sentence |
| "The agent server at … does not accept the host name …" | Add the name to `ADF_DAEMON_ALLOWED_HOSTS` on that computer and restart the server |
| "The TLS connection to … failed" | Give the server a certificate this computer trusts, or use an SSH tunnel. Studio has no option to skip certificate checks |
| "… answered a redirect" | Enter the daemon's final URL |
| "… does not answer as an agent server" | Wrong address or port |
| "… speaks client API N; this Studio needs M." | Update the daemon on the server (or Studio) to the same version |
| "No token is saved for … or it cannot be decrypted on this computer." | **Add** the connection again |
| "The OS keychain did not give the token for *name*; …" | Allow ADF Studio in the keychain prompt, or pair again |
| "*url* is not *name* (fingerprint …, paired as …); the token was not sent." | Another computer answers at the saved address. Studio checks this before every new connection (launch, a dropped connection, wake, Reconnect), sends nothing, and stops. If that computer was set up again, remove *name* and pair again |
| "*url* could not prove it is *name*; the token was not sent." | Something at the saved address shows *name*'s fingerprint but does not hold this computer's token. Studio sends nothing and stops. Check the address |
| "*name* runs an older ADF; update it." | The computer cannot prove who it is. Update ADF there; Studio sends no token to it until then |
| "*name* does not know this computer's token, which was not sent; pair it again." / "*name* removed this computer's access; pair it again." | Pair again |
| "Waiting for the list of saved connections …" | `cli-remotes.json` cannot be read. Fix or remove the file it names; Studio connects once it can read it |

### Files on the server

Agent files live on the server. Where Studio would show a file dialog of this
computer, it shows a picker of the server's folders instead (Open agent…,
New agent, Track folder, folder fields). Its locations are the server's home
folder, each tracked folder and the agents folder, listed separately. With
`ADF_DAEMON_BROWSE_ROOTS` set on the server, those folders replace the home
folder. New agent asks before it replaces a file ("*name*.adf already
exists in this folder. Replace it?").

A `.adf` of this computer that you open by double-click, from the command
line or through a second Studio instance is offered as an upload: "*name*.adf is on this
computer, not on *host*." **Upload a copy…** asks for a tracked folder or the
agents folder on the server and uploads a copy (progress in the task bar).
The copy is a separate agent that needs review before it runs; the file here
is not changed. Nothing is uploaded without your choice. A failed upload says
"Uploading *name* to *host* failed: …" or "*host* did not take the copy of
*name*: …"; if the server already knew the agent, the copy gets a new id. A path that is on
neither machine answers "No agent file at *path* on *host* (…)".

Downloads (Share → save a copy, drag an agent out, download a file) read the
server's copy.

### Sign-in pages

When the remote daemon wants to open an MCP sign-in page, Studio asks first:
"Open a sign-in page on *page host*? The agent server at *daemon host* asks to
open *page host* in your browser (…). Open it only if you started this
sign-in." Studio opens only https pages on public addresses, at most one
every 5 seconds, and takes the browser's callback on this computer and hands
it to the daemon. A refused page says why: "The ADF daemon sent a sign-in page
Studio does not open: …". If the callback port is in use here: "Port N on
this computer is in use, so Studio cannot take the sign-in callback for the
daemon. …". ChatGPT sign-in relays its callback the same way in every mode.

### What stays on the server

| Action | On a runtime on another computer |
|---|---|
| Reveal in folder, Reveal template | A dialog: "This file is on *host*." (or "The templates folder is on *host*.") with the path and **Copy path** |
| Back up seed phrase, Import identity, Restore identity | Disabled, with the commands to run on the server (`adf identity new`, `adf identity restore`, `adf identity import`). Studio does not send a seed phrase to another machine; this holds through an SSH tunnel too |
| Stored credential values (Identity tab, provider key field, MCP and channel forms) | Never sent. Reveal and the provider key field say "Stored credential values stay on the daemon's machine: a remote daemon never sends them to Studio."; the MCP form and Identity values show a placeholder; the channel form shows the key as stored. Leave a placeholder as it is to keep the stored value, or clear the field and type the whole new value. An edited placeholder is refused ("… was shown as a placeholder …, so an edit of it cannot be saved.") |
| Locked credentials question | Names "the daemon's machine" instead of "this machine" |
| Agent browser viewer | Not shown: "The browser viewer needs the daemon on this computer: the container's noVNC port is on the remote server's loopback." When an agent opens a browser, a notification says so |
| LAN firewall check | "Change on *name*." No Fix button |
| Remote access, Allowed networks, Devices | Settings → Networking shows **Remote access** with "Change on *name*."; the network status line is not shown |
| Owner identity (back up, import, restore) | "Change on *name*." under Owner Identity; run `adf identity …` on the server |
| Agent endpoints, Agent directory URL | Not shown: they are the server's loopback addresses |
| Open Daemon Log | Disabled; run `adf daemon logs` on the server |
| Recent files | Paths on the server, listed under its name in Open Recent; not added to the OS recent documents |

Providers, MCP servers, channels, compute and the mesh act on the server:
`localhost` in a provider URL means the server.

## Remote access

Another computer uses the agents on this computer: Studio on a laptop
connects to the daemon on your desktop. This works while Studio runs agents
on ***name* (Local)**; the daemon must be running. Design:
[remote-access.md](https://github.com/christianbalevski/adf/blob/v0.8.3/docs/design/remote-access.md).

On this computer, **Settings → Connections → Add → Share** asks for consent
when remote access is off or a network here is not allowed:

> Devices that you pair on *network* get full control of this server. This
> control is equal to your seed phrase.

It names every network this computer is on, those you allowed earlier
too, with "Public network. The token is sent unencrypted." when Windows
calls one of them Public, or on macOS and Linux, which do not say. With
more than one server, "this server" is ***name* (Local)**: Share always
shares the local server. **Allow** opens one dialog of the OS,
titled "Share", with the same: every network remote access will listen on
(those allowed on another visit included), the Public warning, and on
Windows "Windows may ask whether ADF Studio may accept connections. Choose
Allow on private networks." **Allow** there turns remote access on and
allows exactly the networks it named. Only Settings in the main window
can do this; an agent window cannot.

Leaving Share (**Back**, **Cancel**, closing the dialog, or a reload of the
window) is decided in Studio's main process, not in the page. It closes the
pairing window Share opened, and when Share turned remote access on and no
device was added, it turns remote access off again and says "Remote access
is off again. Share turned it on, and no device was added." While a device
waits for **Allow device**, it changes nothing and says "A device waits for
Allow device. Remote access stays on." **Back** and **Cancel** are disabled
while the **Share** dialog is open. When Share changed something that
stays, it says "Remote access stays on. To turn it off, use Devices."

The **Remote access** switch in **Devices** turns it on or off too; turning
it on there asks once, in a dialog titled "Turn on remote access":

> Devices that you pair or add get full control of the agents of this
> server. A device token is as powerful as your seed phrase.

It names the networks you allowed, which it listens on, with the Public
warning for one of them; a network not allowed yet waits for **Allow**.

A paired device can attach an MCP server or adapter with any command and
start an agent, so it can run code as you and read the owner seed phrase
from the keychain. Pair only devices you trust with the phrase.

The daemon is not restarted: it starts listening on this computer's private
network addresses and its Tailscale address, and running agents keep
running. It never listens on a public address or on a network you did not
allow. Turning remote access off closes those listeners and disconnects
every device; the device list is kept. In the terminal: `adf daemon remote
on|off|status`.

### Network status

The mesh's LAN mode (Settings → Networking → **Network**, or an agent with
`lan` or `public` visibility) and remote access follow the same consent.
Nothing listens on a network until you allow it, once per network, on
every OS. A Windows Private network and the tailnet need it too. A network
is its router (the gateway's MAC address) and its subnet. The Wi-Fi name
counts too where ADF can read it without asking for a permission: on Linux,
and on macOS before 14.4. Windows does not count it. The tailnet is its
name. ADF asks the router for its MAC address at every check (every 10
seconds). A router that does not answer is an "Unidentified network":
nothing listens there and it cannot be allowed. Studio says why
([Settings › Unidentified network](https://agentdocumentformat.org/studio/settings#unidentified-network)).

Limit: anyone who knows your router's MAC address, a former guest for
example, can copy it onto their own router with the same subnet. ADF then
takes it for your home network and listens there. They still need a device
token, or your Allow during a pairing window, to do anything.

Consent is given in three places, all the same list (`allowedNetworks` in
`remote-access.json`): **Allow** in **Share**, **Allow** on the status card
of Settings → Networking ([Settings › Network status](https://agentdocumentformat.org/studio/settings#network-status)),
and **Allow** in the strip below. **Networks** in Settings → Networking
lists every network you allowed; **Remove** closes its listeners at once.

When remote access or the mesh's LAN mode is on and you join a network you
have not allowed, a strip under the title bar names the service that
waits, with **Allow** and **Dismiss**:

| Strip | When |
|---|---|
| "Remote access paused on *network*." | Remote access is on |
| "Agent sharing paused on *network*." | Only the mesh's LAN mode is on |
| "Remote access and agent sharing paused on *network*." | Both |
| "Public network. The token is sent unencrypted." | Under it, when remote access waits and Windows calls the network Public, or on macOS and Linux, which do not say |
| "Public network. Anyone on it can reach the agents you share." | The same, when only the mesh waits |

An unidentified network has **Networking** instead of **Allow**. The strip
does not block the window, and it shows once per network until Studio
restarts, also when the Wi-Fi drops and comes back. In the terminal: `adf
daemon remote status` shows the networks, `adf daemon remote
allow-network` and `forget-network <id|name>` change them. A device can
never allow a network.

Remote access's own line, under the **Remote access** switch in
**Devices**:

| Line | Meaning |
|---|---|
| "Listening on *addresses*." | Other devices reach this computer there |
| "Off." | Remote access is off |
| "Paused on *network*." | No address listens: allow the network (above) |
| "No LAN or tailnet address." | No LAN or Tailscale address; listening starts again when one appears |
| "Not listening: *reason*." | The network is allowed but nothing listens, for example another program uses the port |

While Studio stops the server at quit (it started it, and **Keep running
after Studio quits** is off), the row says "When you quit Studio, Studio
stops this server. Then devices cannot connect until you start Studio
again. To change this, turn on Keep running after Studio quits." There is
no second quit control here.

### Share

**Add → Share** starts with **Share this server as**, the name devices
see. It is the runtime alias (Settings → Identity), so a change there and
here is the same change; it is saved on Enter or when the field loses the
focus, with "Saved." under it. Moving the focus to **Back** or **Cancel**
does not save it. A blank name shows "Enter a name."; a name the server
refuses shows "Use 1 to 63 characters. Do not use control characters." After consent it shows:

1. **Code**: a 6-digit code, in large digits, with the time left (2
   minutes), the tries left (20) and this server's fingerprint. Share opens the pairing
   window itself; **Back** or **Cancel** before a computer claims it closes
   it. A code that expired, or closed after too many wrong codes, offers
   **Renew** for a new one. Below it, when the daemon sees a firewall block
   or cannot read the firewall (Linux), **Firewall** says what to do, with
   the commands to run.
2. **Addresses**: one table, grouped by network, one row per address. Each
   row has the address, its label and its own **Copy** ("Copied" for a
   moment after a click):

   | Group | Address | Label |
   |---|---|---|
   | Tailscale | `https://<machine>.<tailnet>.ts.net` (`tailscale serve`), then `http://100.x.y.z:7385` | Encrypted |
   | The LAN's name, for example "Wi-Fi (192.168.1.0/24)" | `http://192.168.x.y:7385` | Not encrypted |
   | Other | `http://<name>.local:7385`, an address of no known network | Not encrypted |

   Under the table, when an address is plain http: "Some addresses use
   http. Anyone on those networks can read the token."

   Prefer the encrypted ones. Settings → Networking → Advanced → **HTTPS**
   turns on `tailscale serve`; it shows the command (`tailscale serve --bg
   7385`) and runs it only after you confirm.

On the other computer: **Add → Connect**, pick this computer (or type one
of the addresses) and enter the code ([Connect](#connect)). With the CLI:
`adf pair`. This computer then shows the **Allow device** dialog. Its first
line is where the request came from ("From *address* (this network)", and
the Tailscale user when known); the name the device chose is quoted below
it. Check the address. **Allow** or **Deny**. When Studio is in the
background, an OS notification opens it. After **Allow**: "Approved:
*name*." and **Done**; the notice "Device added: *name*."

**Token** (folded under the addresses) creates a token instead: "A token
connects without a code. Scripts and the ADF CLI use tokens."
**Device**, then **Create** shows a device token (`adfd_…`) with **Copy**
and **Done**: "Token for *name*. Studio shows it only one time. It is as
powerful as your seed phrase." After **Done** it cannot be shown again. If
it is lost, revoke the device and add it again. On the other computer:
"click Add, then Connect, and enter the token." In the terminal: `adf
daemon devices add <label>`.

This computer's name for other devices is its runtime alias (Settings →
Identity → Runtime alias), else its host name: the same name in mDNS, the
pairing dialog and other devices' lists.

The code alone never pairs a device: you must also allow it. Five wrong
codes from one device lock that device out of the window ("Pairing: a device
was locked out after 5 wrong codes."); the window shows how many are locked
out and stays open for others. Twenty wrong codes in all close it ("Pairing
closed after too many wrong codes."); open a new one. Both limits are
accepted as they are: a window you open allows at most 20 guesses out of a
million codes, and a device that guesses wrong 5 times is shut out of that
window without blocking the others.

Behind `tailscale serve`, every tailnet user arrives from this computer's
own address, so all of them count as one device, and **Allow device** says
"through tailscale serve (user unverified)". Setting
`ADF_DAEMON_BEHIND_PROXY=1` for the daemon gives per-user limits and the
verified Tailscale login in **Allow device**; it trusts every process on
this computer to tell the truth about the user (see remote-access.md §9).

The token in `adf daemon token` (this computer's own) is refused from other
devices. In the terminal, `adf daemon pair` opens the same pairing window.

### Devices

**Devices** in Settings → Connections ("Devices that can access *name*
(Local).") holds the **Remote access** switch ("Devices that you pair can
connect to *name* (Local).") with its line (below), then the devices that
use the local server: each name, how it was added (Paired or Token), and
"Connected now", "Last seen *time* (*address*)" or "Never connected"; "None.
To add a device, click Add, then Share." without any. Its heading says
"Off", "On" or "On · *N* devices"; outside Local mode "Not available".
**Revoke** asks in a **Revoke device** dialog: "*name* is disconnected now
and its token stops working." After it: "Device revoked: *name*." In the
terminal: `adf daemon devices [list|add|revoke]`.

### Connect

**Add → Connect** lists the ADF computers with remote access on, found on
this network (mDNS) and on your tailnet. A server already saved is its
row under **Remote servers**.

The list, the mesh's list in Settings → Networking and `adf pair` read one
discovery feed: one announcement per computer carries both the mesh and
remote access, and one search covers this network and the tailnet. A
computer announces remote access only while it is on and its network is
allowed. Its announcement on this network names its tailnet addresses, so a
computer on both is one entry, at its tailnet address.

A computer seen at two addresses that are not merged is listed once per
address. Pick only the one whose fingerprint matches the one the host
shows next to its pairing code.

Picking one fills in its address: "*name* at *address*, fingerprint
*fingerprint*.", and, for a plain-http address, **Send without
encryption**. **Connect** with a code shows the fingerprint to check, and
**Pair** sends the code. Then "Waiting for
*host* to allow this device…". When the host allows it, Studio saves the
connection where `adf pair` saves it ([Saved connections and
adf](#saved-connections-and-adf)), pinned to the host's fingerprint, and
connects to it. When the host also answers at a Tailscale address (a
tailnet IP or a `*.ts.net` name) with the same fingerprint, the
**Encrypted address** dialog offers to save that one instead. A saved
connection is never moved to another address without the **Use new
address** dialog ("*name* is now at *url*."). The dialog then shows **Done**.

| Message | What to do |
|---|---|
| "Wrong code. *N* tries left." | Enter the code shown on the host |
| "Too many wrong codes from this computer for this pairing window. …" | This device is locked out of that window: on the host, **Add → Share** again |
| "Wrong code and no tries left; …" | On the host, **Add → Share** again for a new code |
| "The pairing window on *host* is closed; …" | The 2 minutes passed or the host cancelled: open a new window |
| "*host* has no pairing window open; on it choose Add, then Share." | Open **Share** on the host first |
| "*host* denied this device." | The host chose Deny |
| "Studio could not reach *host* at *url*. The host's firewall may block port 7385." | See [Firewall](#firewall) |
| "*host* is already asking about another device. …" | Wait, then try again |
| "*url* has remote access off. …" | On the host: **Add → Share** |
| "*host* runs an older ADF. Update ADF there, then pair again." / "*host* runs an older ADF; update it." | The host's ADF predates this feature or cannot prove who it is |
| "*url* could not prove it is *host*; Studio saved nothing, so remove "*device*" on *host*." | The address did not prove it issued the token it just delivered. Remove the device on the host and pair again |
| "*file* … Fix or remove it; nothing was changed." | The list of saved connections cannot be read; nothing was sent to the host. Fix or remove the file |
| "*address* now answers with fingerprint *X*, not *Y* as when *name* was paired; Studio sent nothing, and if it was set up again, remove *name* and pair again." | Another computer answers at the saved address. If that computer was set up again, remove *name* first |
| "The approval came with fingerprint *X*, but *host* showed *Y*. …" | Nothing was saved; revoke the device on the host and pair again |
| "Kept the saved address of *name*; nothing was sent." | You chose Cancel in Use new address |

### Firewall

Windows asks the first time whether ADF Studio may accept connections:
choose **Allow** on private networks. macOS may ask whether ADF Studio may
find devices on the local network: choose **Allow**. Studio adds no firewall
rule itself. On Linux, open port 7385 for your LAN, for example
`sudo ufw allow from 192.168.0.0/16 to any port 7385 proto tcp`. For the
mesh port, Settings → Networking → Advanced → **Firewall** shows the exact
commands to run in an administrator shell.

### Quit with devices connected

When Studio would stop the server (Studio started it and **Keep running
after Studio quits** is off) and a device is connected, quitting Studio asks first,
every time, in a **Quit** dialog: "*N* devices connected", "Keep the daemon
running for them, or stop it." When Studio cannot read whether devices are
connected, it asks the same with "Devices may be connected".

**Keep running** leaves the daemon running after Studio quits, this time
only; the setting does not change. **Stop daemon** stops it and disconnects
them. **Cancel** keeps Studio open. Quitting from the menu, the tray, Cmd+Q
and closing the window on Windows and Linux all ask.

## Agents in two runtimes

On one computer, one agent file runs in one runtime at a time. Each runtime
(Studio in Inside Studio mode, a daemon) takes a lease on the agent file when it starts
the agent. Starting an agent another runtime runs is refused with code
`agent_leased` and a sentence naming the holder:

- "agent-1 is already running in the ADF daemon (pid 4242). Stop it there with
  "adf stop agent-1", or stop that daemon with "adf daemon stop", then start
  it here."
- "agent-1 is already running in another ADF Studio (pid 4242). Stop the
  agent there or quit that Studio, then start it here."

Autostart skips such agents (`leased_elsewhere` in the daemon's autostart
report). A Studio in Local mode runs no agents and holds no leases,
so `adf daemon start` does not refuse it.

One Studio shows the agents of the local runtime and of each saved connection at
the same time; a second Studio is not needed to watch two computers. The
same agent file on two computers is two agents, one per runtime: each is
listed, opened and run on its own computer, and Studio does not pass
messages between computers (their runtimes' mesh does). Lease files, stale leases
and the full list of sentences: [Troubleshooting › Agent is already
running](https://agentdocumentformat.org/cli/troubleshooting#agent-is-already-running-agent_leased).

An agent file that another runtime runs opens in the daemon read-only: you
can read it, and a write answers `agent_leased` with the same sentence.

An action on the open agent while Studio does not hold it in the daemon (it
is not running there and the client session could not hold it) fails with
"*Action* is not available in daemon mode yet: W2-B (*path* is not running in
the daemon, and holding it open needs a client session)". Open the agent
again; if it repeats, restart Studio.

## Message index

Every message the backend features show, and where it is explained. Text in
*italics* varies.

| Message (start) | Section |
|---|---|
| "Next launch: *name*." / Restart | [Switch the backend](#switch-the-backend) |
| "*name* is in Settings → Connections." / "*name* is no longer saved; …" | [Upgrading from remote mode](#upgrading-from-remote-mode) |
| "macOS asks once whether the ADF daemon may read Studio's runtime key from the keychain." | [Upgrading from 0.7.x](#upgrading-from-07x), [Troubleshooting](https://agentdocumentformat.org/cli/troubleshooting#macos-keeps-asking-for-keychain-access) |
| "Agents now run *on B*." / "… part of the handover is not done." | [What moves](#what-moves-during-a-switch), [When a move is not done](#when-a-move-is-not-done) |
| "Agents now run in a background service on this computer (the ADF daemon)." / Open the Guide | [Upgrading from 0.7.x](#upgrading-from-07x) |
| "Default changed" (Settings → Connections) | [Upgrading from 0.7.x](#upgrading-from-07x) |
| "Inside Studio (legacy)" | [Run agents inside Studio when the daemon does not work](#run-agents-inside-studio-when-the-daemon-does-not-work) |
| "Agents now run in a background service on this computer (the ADF daemon), but Studio could not connect to it." | [Upgrading from 0.7.x](#upgrading-from-07x) |
| "An older ADF daemon (adf …) is running and uses the same settings." / "An ADF daemon that Studio cannot identify …" | [Upgrading from 0.7.x](#upgrading-from-07x) |
| "Studio cannot use its backend settings file." / "… or replace its backend settings file." | [Upgrading from 0.7.x](#upgrading-from-07x) |
| "Studio and the ADF daemon are signed in to … with different accounts." | [Two accounts](#two-accounts-the-conflict-dialog) |
| `auth.replaced.<time>.json` | [Two accounts](#two-accounts-the-conflict-dialog) |
| "not moved back: … still runs on these settings" | [When a move is not done](#when-a-move-is-not-done) |
| "… is missing, so Studio cannot tell its sign-ins from the daemon's own" | [When a move is not done](#when-a-move-is-not-done) |
| Keep running after Studio quits / "When you quit Studio, …" | [Quit Studio](#quit-studio) |
| "The ADF daemon keeps running while *N* other client(s) are connected …" | [Quit Studio](#quit-studio) |
| "The daemon stays up because this app is connected: …" (terminal app) | [Quit Studio](#quit-studio) |
| "*File* was changed by … while you were editing." / Reload / Keep mine | [Changed elsewhere](#changed-elsewhere) |
| "Discard your unsaved changes to …?" | [Changed elsewhere](#changed-elsewhere) |
| "Studio kept your unsaved version of …" / Show folder / Dismiss | [Changed elsewhere](#changed-elsewhere) |
| "… was changed by … after you opened it." / Overwrite / Reload theirs (terminal app) | [Changed elsewhere](#changed-elsewhere) |
| "Live events over /events: …" (terminal app) | [Streaming in the terminal app](#streaming-in-the-terminal-app) |
| Help menu "ADF daemon: …" / Reconnect to the ADF Daemon / Open Daemon Log | [Local server status](#local-server-status) |
| "Studio cannot show stored values or import an identity. …" / "Local proof: not available (…)" / "Key not trusted" | [Local server status](#local-server-status) |
| "Starting the ADF daemon…" / "Waiting for the ADF daemon (pid N)…" | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Studio lost its connection to the ADF daemon." / "Reconnected to the ADF daemon." | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Studio could not connect to an ADF daemon." and its reasons | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Studio could not reopen … after reconnecting" / "… is locked again after the ADF daemon restarted." | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Saved." and the other Connection page messages | [Messages on the Connection page](#messages-on-the-connection-page) |
| "Uploading … failed" / "… did not take the copy of …" | [Files on the server](#files-on-the-server) |
| "Cannot reach daemon at …" | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Emergency stop did not reach the ADF daemon." / "Emergency stop was partial." | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Could not open the daemon log." | [Local server status](#local-server-status) (Help menu) |
| "*Action* is not available in daemon mode yet: W2-B (…)" | [Agents in two runtimes](#agents-in-two-runtimes) |
| "… Its log says: "Failed to start: port 7385 on 127.0.0.1 is already in use"." | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "Run Inside Studio for This Session" (failure dialog, Help menu) | [When the daemon is not reachable](#when-the-daemon-is-not-reachable) |
| "The running ADF daemon is version *X*; this Studio is *Y*." / Restart It Anyway | [Version mismatch](#version-mismatch) |
| "Agents run … because ADF_STUDIO_BACKEND is set." / "… for this session only" | [Run agents inside Studio when the daemon does not work](#run-agents-inside-studio-when-the-daemon-does-not-work) |
| The remote sentences | [Connection problems](#connection-problems) |
| "The OS keychain did not give the token for *name*; …" / "In use." / "Add it first." | [Connection](#connection) |
| "No fingerprint; identity not checked." / "Saved without a fingerprint; identity not checked." / "Replace connection" | [Add](#add) |
| Unencrypted / "This address uses http. …" / "Enter the 6-digit code." | [Add](#add) |
| "Waiting for the remote ADF daemon at …" | [Connection problems](#connection-problems) |
| "Turn on remote access" / "Devices that you pair … get full control of this server. …" / "When you quit Studio, Studio stops this server. …" / "Change on *name*." | [Remote access](#remote-access) |
| "Remote access paused on …" / "Agent sharing paused on …" / Allow / Dismiss / "Public network. …" / "Paused on …" / "Listening on …" | [Network status](#network-status) |
| Share this server as / "Enter a name." / "Allow device" / "Approved: *name*." / "Some addresses use http. …" / "Remote access is off again. …" / "A device waits for Allow device. …" / Encrypted / Not encrypted / Copy / Renew / "No code." / Firewall / Token / "Remote access stays on. To turn it off, use Devices." / "Pairing: a device was locked out after 5 wrong codes." / "Pairing closed after too many wrong codes." / "Device added: …" | [Share](#share) |
| "Revoke device" / "Device revoked: …" | [Devices](#devices) |
| Connect / Share / "Connect to a remote agent server." / "Share this server." / "No server found yet. On the other computer, click Add, then Share." / "Enter a code or a token. …" / "The server at … has a different fingerprint …" | [Add](#add) |
| Local server / Remote servers / Devices / Keep running after Studio quits | [Connection](#connection) |
| "Waiting for *host* to allow this device…" / "Wrong code. …" / "… denied this device." / "… The host's firewall may block port 7385." / "Use new address" | [Connect](#connect) |
| "*N* devices connected" (Quit) / Keep running / Stop daemon | [Quit with devices connected](#quit-with-devices-connected) |
| "*file* uses schema v2, which this version cannot upgrade …" / "… skipped: need upgrade or review" | [Troubleshooting](https://agentdocumentformat.org/cli/troubleshooting#an-agent-file-uses-schema-v2) |
| "*name*.adf is on this computer, not on *host*." / Upload a copy… | [Files on the server](#files-on-the-server) |
| "*name*.adf already exists in this folder. Replace it?" | [Files on the server](#files-on-the-server) |
| "Open a sign-in page on …?" / "The ADF daemon sent a sign-in page Studio does not open: …" | [Sign-in pages](#sign-in-pages) |
| "This file is on *host*." / Copy path | [What stays on the server](#what-stays-on-the-server) |
| "A remote ADF daemon never sends its owner seed phrase …" / "The owner identity of a remote ADF daemon is changed on its machine …" | [What stays on the server](#what-stays-on-the-server) |
| "Stored credential values stay on the daemon's machine …" | [What stays on the server](#what-stays-on-the-server) |
| "The browser viewer needs the daemon on this computer …" | [What stays on the server](#what-stays-on-the-server) |
| "The firewall check applies to this computer, but the mesh server runs on the remote daemon's machine." | [What stays on the server](#what-stays-on-the-server) |
| "… is already running in the ADF daemon (pid N)." (`agent_leased`) | [Agents in two runtimes](#agents-in-two-runtimes) |
| "ADF Studio (pid N) is running agents from the same settings file (…)." | [Studio and the terminal app together](#studio-and-the-terminal-app-together) |
| "Agent leases unavailable: …" / "… its lease file … could not be read or replaced" | [Troubleshooting](https://agentdocumentformat.org/cli/troubleshooting#agent-is-already-running-agent_leased) |
| "*X* was left running: used by …" (Settings → Compute) | [Troubleshooting](https://agentdocumentformat.org/cli/troubleshooting#containers-left-running) |
