Working on a Host

Knowing Where You Are

A window on a host works like a local one: worktrees, terminals, agents, the file browser, diffs, the Review Hub, recipes and fleets all run on the host, against the host's files. A few signals make sure you always know which machine you are looking at:

• The toolbar chip becomes a bordered pill reading SSH · studio-01, and the window title ends in — studio-01.
• Terminal, agent and dev-server panels add @studio-01 after their titles.
• Settings pages say whose values they show: Settings on studio-01 or This Mac.
• Scratch workspaces you create from that window live on the host.

Actions that would open something on the host's own screen act here instead. Reveal in Finder becomes Copy host path, because nobody is looking at the host's file manager.

Settings and Accounts

Every setting belongs either to the host or to the device you are using, and nothing is synced between machines. In a window on a host:

Pages that mix both mark each section with On studio-01 or This Mac, and single rows can note Set on studio-01. A window on this machine shows none of these markers.

Credentials are never copied or synced. Each host signs in to its agent CLIs, its forges and its plugins for itself, and keeps what it stores. Viewing or editing a host's environment variables or plugin secrets from your window sends those values over your ssh connection to show them; they stay stored on the host. The Code Forge pages say so in place: GitHub isn't connected on studio-01. A host's details page in Settings → Hosts lists its agent CLIs and its forge accounts as the host reports them.

Agents on a Host

The agent picker shows what the host has installed. An agent the host lacks is marked Not installed on studio-01, and Settings → CLI agents names the host it is checking. Launching one anyway opens the usual CLI binary not found pane, with install instructions for the host's operating system, a Re-check button and the rest.

• Install agent CLIs on the host the way you normally would, in a terminal on the host, then use Re-check. Daintree reads the host's shell PATH and the usual install locations, so a CLI on the host's PATH is found without restarting anything.
• Daintree never installs an agent CLI on a host because it exists here. Each host is configured as itself.
• Agents keep running on the host when you disconnect, switch away or close your laptop. Agent states are observed from the terminals on the host, as they are locally.

When the Connection Drops

The link is watched continuously. A blip that recovers within a moment shows nothing. A longer drop shows a banner across the window, Connection to studio-01 lost. Reconnecting…, and Daintree reconnects on its own with backoff.

View full size: View full size

• Terminals keep running on the host. Output keeps arriving as soon as the link is back; only your typing is held. Each terminal shows Read-only until studio-01 reconnects, so nothing you type queues up behind a dead link.
• Output catches up. On reconnect, each terminal replays what the host kept for it (up to 4 MB per terminal) and resumes where it left off, or redraws from the host's current screen if it was away long enough for the host to drop the backlog. Output older than that isn't recovered.
• A terminal the host no longer has, because the host restarted, shows [The host no longer has this terminal] and reads as exited.
• No guessing. If an operation's answer was lost with the link (a push, a clone, creating a worktree), the window says Checking with studio-01…, asks the host what happened once it is back, and reports that, rather than assuming success or failure. If the host no longer has a record, for example because it restarted, Daintree says so and asks you to check before trying again.

The host keeps a dropped session resumable for up to ten minutes while it keeps running. A host that stays unreachable shows studio-01 is unreachable · last seen 5 minutes ago with Retry. See Connection States.

Files, Images and localhost

Drops, Pastes and Attachments

Your agents run on the host, so a path on this machine means nothing to them. In a window on a host, anything you drop, paste or attach from this machine is uploaded to the host first, and the host's path is what gets inserted.

• The host inbox. Uploads go to a private folder in the host's temporary directory, outside every worktree, so they never show in git status. Cleanup removes entries older than a day and trims the inbox to about 1 GB, and sending the same file again reuses the copy already there.
• Size. A file over 50 MB asks first, Send 'dataset.csv' to studio-01?; a file over 500 MB is refused. Pasted clipboard images are limited to 20 MB. Folders can't be sent yet.
• Into the project instead. Hold Option (Alt on Linux) while dropping to upload into the project: onto a folder in the file browser, or into an agent's input, where it goes to the terminal's directory. A file with the same name asks before replacing.
• Attach. An agent's attach button becomes a menu: From this Mac… or From studio-01…, which browses the host.
• Images on Ctrl+V. An agent's own Ctrl+V would read the host's clipboard. When your clipboard holds an image, Daintree takes over plain Ctrl+V in agent terminals of a remote window, uploads the image and types its host path. With no image, Ctrl+V reaches the agent unchanged. Turn this off with Send my clipboard images to remote agents on Ctrl+V in Settings → Panel grid, under Agent input.

Uploads show a progress chip you can cancel. Files already on the host, such as those dragged from the window's own file browser, pass through untouched.

Dev Servers and localhost

In a window on a host, localhost means the host's localhost. Daintree forwards ports over the existing ssh connection as you need them, so this machine's browser reaches a server running on the host:

• Browser panels open a host's localhost:5173 through a forward on the same port number here, so the page keeps its address. If that port is busy here, Daintree says so instead of picking another.
• Links in a terminal to a localhost URL forward the port and open it.
• Sign-in flows that redirect to a localhost callback port get that port forwarded first, so a CLI's browser login on the host completes from this machine. Forwards opened from terminal links and sign-ins are temporary and close on their own after about ten minutes.
• Dev Preview reaches the host's dev server through the host and forwards it on demand.

Every forward is listed, and can be added or stopped by hand, in the Ports view. Forwards listen only on this machine's loopback address.

Notifications

• The window's own host notifies you as a local project would. Native notifications are titled with the host, studio-01: …, and use this machine's sounds and mute settings.
• Other hosts stay quiet unless you ask. Turn on Notify me about this host on the host's page in Settings → Hosts and you hear when an agent there is waiting, even while every window shows another machine: studio-01: agent waiting. It appears as a toast when Daintree is in front, and in the inbox otherwise. The host's own quiet hours apply.

The rules for which agent events notify belong to the host; how they look and sound belongs to this machine. See Notifications and Sound.

Plugins Across Machines

In a window on a host, the host's plugins are the ones that run. A plugin's code runs on the host next to the project; its views load from the host and render in your window. Installed plugins and their settings are never synced: a plugin is installed on another machine only when you ask, one at a time.

• On switching, if this machine has plugins the host lacks, a note says 1 of your plugins isn't installed on studio-01 with Review.
• Settings → Hosts → studio-01 → Plugins compares the plugins you installed on each machine (built-in and project plugins aside) in groups: Only on this machine (with Install on studio-01), Different versions (with Update on studio-01 when yours is newer; Daintree never downgrades a host's plugin), Can't run as they are on studio-01 with the reason, Only on studio-01, and Matching plugins. The Hosts overview shows the same as a one-line summary.
• A saved panel from a plugin the host lacks shows Docker Control isn't installed on studio-01, with Install on studio-01 and Remove panel.
• Plugins that only work at the machine say Only works when you're sitting at studio-01.

Because a host plugin's view code runs in your window, Daintree asks before it first loads: Run "Docker Control" from studio-01 on this computer? with Run plugin or Don't run, and asks again when the host changes that plugin's code. Capability prompts (running commands, writing files) appear in the window that has control, and the answer is stored on the host. A plugin on a host that wants this computer's clipboard asks separately, per host and per plugin. Settings → Hosts → studio-01 lists your answers under Plugin views and Clipboard access, each with Reset.

Plugin secrets are stored on each host, encrypted with that host's own keychain or keyring. A Linux host with no usable keyring, which is typical of a headless server, can't save them: No keyring on studio-01 (headless Linux). Use environment variables or the CLI's own login on that host instead.

MCP and the Assistant

Agents on a host talk to the host's own MCP server and see the host's plugin tools. When an action needs a window, the host sends it to the window that has control of that project, wherever it is. With no window attached at all, the host still lets agents open terminals, send them commands and create worktrees. Anything else is refused with a message telling the agent to retry once a window has the project open.

What an agent on a host can do inside your window is limited to project actions: terminals, worktrees, agents, recipes and a browser screenshot. Nothing reaches this machine's clipboard, files, editors, settings or plugins. Two host actions are available to agents in the full MCP tier:

• host.switch moves the window to another host. It always asks you first, naming the agent's host: Agent on host "studio-01".
• project.openOnHost only opens the Continue a Branch dialog. Every push, clone and switch in it is still your click.

The Daintree Assistant runs on the host when the window is on a host, using the agent CLI and settings there.

Who Has Control

Several windows, on several machines, can show the same host project. One machine at a time has control of it: its windows type into the terminals, resize them, change worktrees, Git and layout, and receive agents' MCP actions and plugin prompts. Every other window showing the project is viewing: output and state keep updating live, but typing and changes are refused. The host's own screen counts as one more machine, and its windows share control when it has it. On a client, control belongs to one window at a time, and passes to another window of the same machine when that window closes.

• Opening takes control. Opening a host project from your machine takes control automatically, unless another client machine already has it. Then the window opens viewing.
• Viewing is marked. The window shows Greg's MacBook Pro has control of this project · Viewing here with Take control, the chip adds viewing, and each terminal reads Read-only · Greg's MacBook Pro has control.
• Taking control is one click. The terminal confirms with You have control of this project and the keyboard returns to it.
• Short grace. If the machine with control drops off, the project stays reserved for it for 15 seconds, and for 45 seconds after the host restarts, so a reconnecting window gets it back rather than whichever window opens first.

View full size: View full size

Drafts in the input bar are per window and aren't mirrored; what reaches the terminal is the same for everyone. On the host's own screen, a pill names the machines connected to it; see The Host's Own Screen.