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
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.
| 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). 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):
- Local server (“The agent server on this computer.”): name (Local) (Local server).
- Remote servers (“Agent servers on other computers that this Studio connects to.”): the saved connections (Remote servers).
- 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:
| 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). 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:
| 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) |
| 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). Only in Local mode; otherwise disabled, with the reason in its tooltip |
Back returns to the two cards.
Connect shows everything on one form:
- 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) orhttp://100.x.y.z:7385(a tailnet address). Any otherhttp://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.” - 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.
- 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.
- 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. - 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.
- A code is 6 digits. Anything else shows “Enter the 6-digit code.” under Code, and Connect stays disabled.
- 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):
- 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.
- It saves
"mode": "local"tostudio-backend.json. - It starts the daemon, which starts the agents set to start automatically, from the same tracked folders as Studio did.
- 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 |
| “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:
| 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:
- in
studio-client-settings.json, moves that computer’s Open Recent (remoteRecentFiles) toruntimeRecentFiles, its Mesh view groups, stewards and layout (fleetGroups,fleetStewards,fleetMapState) toruntimeFleet, and its saved agent windows (agentWindows) to its runtime, each with the fingerprint it was paired with; - writes
"mode": "local"tostudio-backend.json, removesremote.name, and writesruntimeOrderwith the connection that was in use first, then the other saved connections in the order they were paired; - 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.
-
Only this branch’s builds on the machine. Quit the release Studio, or uninstall it, and stop the daemon of an
adfinstalled from npm (adf daemon stop), then uninstall that package. Then check:adf daemon statusreports 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>.jsonof a process that is not this build’s Studio or daemon. Each file names itskind,pid,versionandsettingsPath. A runtime of another build there runs agents from the same files.
-
After the first launch in Local mode, confirm the daemon took over Studio’s identity and can prove it is local:
adf identityshows the runtime asstudio (adopted). Anything else means agents made by Studio stay locked in the daemon.adf daemon statushas noproof unavailableline. With that line, owner import and the stored-value reveal (Settings → Providers keys, Identity panel Reveal) refuse until the daemon restarts.
-
No owner switch from the terminal during the week. Do not run
adf identity importwith 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. -
Watchdogs that look for Studio by process name do not see a dead Studio. The daemon Studio starts is
ADF Studio.exe(orADF Studioon 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. -
The way back, in this order:
- Settings → Connections → Inside Studio (legacy) → Connect, then Restart.
- 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.
- Stop the daemon:
adf daemon stop. - Reinstall the release (v0.7.8).
Do not use
ADF_STUDIO_BACKEND=embeddedas the way back. It runs agents inside Studio without running the handover, so credentials moved to the daemon stay there.
Switch the backend
- 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).
- Studio saves the mode. Nothing restarts and no agent stops. The page shows “Next launch: name.” with Restart.
- 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
| 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 |
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.
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.
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)”.
| 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 restartreads “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 statusin a terminal: alsostarted by …, andproof 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
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), 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:
- 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 theADF_DAEMON_TOKENof 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. - 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 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.
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:
| 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:
-
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.
-
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), thenhttp://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 Other http://<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.
| 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 |
| “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.” / Restart | Switch 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 Guide | Upgrading 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>.json | Two 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 mine | Changed elsewhere |
| “Discard your unsaved changes to …?” | Changed elsewhere |
| “Studio kept your unsaved version of …” / Show folder / Dismiss | Changed 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 Log | Local 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 reasons | 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 |
| “Saved.” and the other Connection page messages | Messages 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 Anyway | Version 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 sentences | Connection 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 quits | 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 |
| “N devices connected” (Quit) / Keep running / Stop daemon | Quit 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 path | 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 |
| “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 |