On this page

ADF Studio runs agents in one of two modes. You choose it in Settings → Connections (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.

ModeAgents run inTypical use
LocalA background service on this computer, with the same settings file and agent files as StudioThe 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 processA 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). 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). 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).

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 lists each difference.

Connection

Settings has two groups (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), then three sections, from top to bottom (design: multi-runtime.md §6.5):

  1. Local server (“The agent server on this computer.”): name (Local) (Local server).
  2. Remote servers (“Agent servers on other computers that this Studio connects to.”): the saved connections (Remote servers).
  3. Devices (“Devices that can access name (Local).”): the other computers and Studios that use the local server (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:

RowStateAction
name (Local)Connected (or Connecting, Not connected, retrying, Not connected); none while Inside Studio runsNone; Connect while Inside Studio runs
Inside Studio (legacy), only while it runs or is savedConnected, or noneConnect

Details under the name shows the pid, who started the server, its URL, its version and the trust in its key (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).

In Local mode the section also holds Keep running after Studio quits (Quit Studio), the one quit setting, and “Default changed” after the upgrade from 0.7.x (Upgrading from 0.7.x).

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), 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), 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:

CardIconHelp lineUse
ConnectA computer, an arrow out to a server“Connect to a remote agent server.”This Studio uses a remote server (Connect)
ShareComputers, arrows in to a server“Share this server.” (“Share name (Local).” while a connection is saved)Other devices use the local server (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). 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):

  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:

TextMeaning
“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
“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 appears during the first launch, on the small “ADF Studio is starting” window.

Two cases stop the first launch from moving anything:

DialogMeaningWhat 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 themStop 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 modeChoose one. Studio saves it, then moves your sign-ins to that side
“Studio cannot use or replace its backend settings file.” with … for This LaunchThe file cannot be read (for example EACCES); the dialog names the path and the errorFix 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.

  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).
  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). 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): 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).

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

MessageMeaning
“Saved.”You chose the mode this launch already runs
“Next launch: name.” with RestartThe 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

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.

StateInside Studio → LocalLocal → Inside Studio
Running agentsStop when Studio quits; the daemon starts the ones set to start automaticallyA 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.jsonMoved back
Runtime identityStudio’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 reviewThe keychain copy is deleted
ChatGPT and Grok sessions<provider>/auth.json moves to <provider>/auth.daemon.jsonMoved back
App-level MCP sign-insMoved into the daemon’s keychain entries. They stay in Studio when the keychain cannot be opened or is locked; agents keep their own sealed copiesMoved 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 phraseMirrored into the keychain entry ADF / owner-mnemonic when it is not thereNothing
Open agent and tabsReopened after the restartReopened 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.

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 textWhat 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 saysWhen
“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
SettingWhen you quit StudioAfter a Studio crash
OffStudio stops a daemon it started, as quitting stops agents in Inside Studio modeThe daemon stops 60 seconds later
OnThe 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.

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.

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)”.

ButtonWhat happens
ReloadShows their version; your unsaved text is discarded
Keep mineSaves 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 seeMeaningWhat to do
Task-bar progress and the line “Starting the ADF daemon…”Studio is starting the daemonWait; 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 settingsWait
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 secondsCheck 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 LogNo 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 doneRetry after the reconnect
A chat waiting for its answer ends after 15 seconds without the daemonStudio stops waiting; the daemon may still run the turnReopen the agent after the reconnect
Dialog “Emergency stop did not reach the ADF daemon. … Agents may still be running.” (after Kill)The stop request failedRun 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 restStop 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 reconnectOpen 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 passwordOpen 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:

ReasonFix
“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 logOpen 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

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.”

ButtonWhat happens
Restart the Daemon with Studio’s VersionStops that daemon and its agents, starts this Studio’s daemon, which starts the agents set to autostart
Run Inside Studio for This SessionStudio 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), 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. 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, Connect). A token is a device token from Share → Token on the other computer (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.
  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).

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).

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 withFix
“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

ActionOn a runtime on another computer
Reveal in folder, Reveal templateA 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 identityDisabled, 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 questionNames “the daemon’s machine” instead of “this machine”
Agent browser viewerNot 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, DevicesSettings → 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 URLNot shown: they are the server’s loopback addresses
Open Daemon LogDisabled; run adf daemon logs on the server
Recent filesPaths 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.

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).

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), 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:

StripWhen
“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:

LineMeaning
“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):

    GroupAddressLabel
    Tailscalehttps://<machine>.<tailnet>.ts.net (tailscale serve), then http://100.x.y.z:7385Encrypted
    The LAN’s name, for example “Wi-Fi (192.168.1.0/24)”http://192.168.x.y:7385Not encrypted
    Otherhttp://<name>.local:7385, an address of no known networkNot 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). 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), 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.

MessageWhat 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
“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.

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.” / RestartSwitch the backend
“name is in Settings → Connections.” / “name is no longer saved; …”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, Troubleshooting
“Agents now run on B.” / ”… part of the handover is not done.”What moves, When a move is not done
“Agents now run in a background service on this computer (the ADF daemon).” / Open the GuideUpgrading from 0.7.x
“Default changed” (Settings → Connections)Upgrading from 0.7.x
“Inside Studio (legacy)”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
“An older ADF daemon (adf …) is running and uses the same settings.” / “An ADF daemon that Studio cannot identify …”Upgrading from 0.7.x
“Studio cannot use its backend settings file.” / ”… or replace its backend settings file.”Upgrading from 0.7.x
“Studio and the ADF daemon are signed in to … with different accounts.”Two accounts
auth.replaced.<time>.jsonTwo accounts
“not moved back: … still runs on these settings”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
Keep running after Studio quits / “When you quit Studio, …”Quit Studio
“The ADF daemon keeps running while N other client(s) are connected …”Quit Studio
“The daemon stays up because this app is connected: …” (terminal app)Quit Studio
“File was changed by … while you were editing.” / Reload / Keep mineChanged elsewhere
“Discard your unsaved changes to …?”Changed elsewhere
“Studio kept your unsaved version of …” / Show folder / DismissChanged elsewhere
”… was changed by … after you opened it.” / Overwrite / Reload theirs (terminal app)Changed elsewhere
“Live events over /events: …” (terminal app)Streaming in the terminal app
Help menu “ADF daemon: …” / Reconnect to the ADF Daemon / Open Daemon LogLocal server status
“Studio cannot show stored values or import an identity. …” / “Local proof: not available (…)” / “Key not trusted”Local server status
“Starting the ADF daemon…” / “Waiting for the ADF daemon (pid N)…”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
“Studio could not connect to an ADF daemon.” and its reasonsWhen 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
“Saved.” and the other Connection page messagesMessages on the Connection page
“Uploading … failed” / ”… did not take the copy of …”Files on the server
“Cannot reach daemon at …”When the daemon is not reachable
“Emergency stop did not reach the ADF daemon.” / “Emergency stop was partial.”When the daemon is not reachable
“Could not open the daemon log.”Local server status (Help menu)
“Action is not available in daemon mode yet: W2-B (…)”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
“Run Inside Studio for This Session” (failure dialog, Help menu)When the daemon is not reachable
“The running ADF daemon is version X; this Studio is Y.” / Restart It AnywayVersion mismatch
“Agents run … because ADF_STUDIO_BACKEND is set.” / ”… for this session only”Run agents inside Studio when the daemon does not work
The remote sentencesConnection problems
“The OS keychain did not give the token for name; …” / “In use.” / “Add it first.”Connection
“No fingerprint; identity not checked.” / “Saved without a fingerprint; identity not checked.” / “Replace connection”Add
Unencrypted / “This address uses http. …” / “Enter the 6-digit code.”Add
“Waiting for the remote ADF daemon at …”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 paused on …” / “Agent sharing paused on …” / Allow / Dismiss / “Public network. …” / “Paused on …” / “Listening on …”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
“Revoke device” / “Device revoked: …”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
Local server / Remote servers / Devices / Keep running after Studio quitsConnection
“Waiting for host to allow this device…” / “Wrong code. …” / ”… denied this device.” / ”… The host’s firewall may block port 7385.” / “Use new address”Connect
“N devices connected” (Quit) / Keep running / Stop daemonQuit with devices connected
“file uses schema v2, which this version cannot upgrade …” / ”… skipped: need upgrade or review”Troubleshooting
“name.adf is on this computer, not on host.” / Upload a copy…Files on the server
“name.adf already exists in this folder. Replace it?”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
“This file is on host.” / Copy pathWhat 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
“Stored credential values stay on the daemon’s machine …”What stays on the server
“The browser viewer needs the daemon on this computer …”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
”… is already running in the ADF daemon (pid N).” (agent_leased)Agents in two runtimes
“ADF Studio (pid N) is running agents from the same settings file (…).”Studio and the terminal app together
“Agent leases unavailable: …” / ”… its lease file … could not be read or replaced”Troubleshooting
“X was left running: used by …” (Settings → Compute)Troubleshooting