Locations: run atrium work on another machine

A location is a machine that can own atrium projects, rooms, panes, tasks, notes, and agent sessions. Your Mac is the local location. Add a Linux box over SSH and it appears in the same workspace UI; atrium routes each operation to the daemon that owns the data.

The macOS app is still the control surface. A remote location is not a hosted atrium cloud workspace: it is a box you control, connected directly over SSH, running its own atriumd.

What runs where

Surface	macOS client	Selected location
Windows, sidebars, mosaic, approvals	Renders and controls them	Sends live state to the client
Repositories and project files	Local projects only	Remote projects stay on the box
Terminals and agent processes	Local sessions	Owned by the remote atriumd
Scrollback, rooms, notes, task state	Shows a unified view	Stored by the owning daemon
Agent credentials and publishing access	Managed per location	Stored and used on that location

Traffic goes directly between your Mac and the box over SSH. atrium's service does not proxy your repository, terminal, or agent traffic.

Add a location

The guided path is Settings → Locations → New location:

1. Enter the box's address, SSH user, and connection details.
2. Let atrium probe the connection and set up a key. If you enter an SSH or sudo password, it is used for provisioning and is not stored.
3. Confirm pairing. atrium installs or updates atriumd, registers the device, and performs a health check.

The host needs Linux on Intel or ARM, an SSH server, and a user that can install the daemon. WSL2 is supported when it is reachable over SSH. The atrium desktop app itself still requires macOS.

If you already have an SSH config alias, the CLI exposes the lower-level path:

atrium remote add my-box --name build-box
atrium remote list
atrium remote inspect build-box

Projects and copies

A project belongs to one location. Create a project on a remote box, or choose a remote location in the launcher and let atrium materialize the project before starting the agent.

The same repository can have related project copies on several machines. atrium links those copies as kin and shows Acting on when the current room is controlling a related copy somewhere else. A copy remains an independent working directory with its own rooms, panes, branches, and sessions; atrium does not pretend the files are one shared filesystem.

Before a remote launch, atrium checks that the project, worktree, adapter, binary, credentials, and requested launch profile are available on the destination. When setup needs a consequential action—creating a project copy, installing a tool, or forwarding credentials—the launcher asks before proceeding.

Work across locations

Location-aware surfaces include:

• The Home and Activity sidebars, rooms, wings, panes, breadcrumbs, and project switchers.
• Terminal, agent chat, editor, file tree, search, source control, viewers, tasks, and notes.
• Cross-location agent discovery and messaging.
• Task creation, dispatch, recurrence, relocation, and a unified board across the locations visible in Home.
• Per-location tools, adapters, agent accounts, publishing credentials, health, and forwarded ports.

The owning location is marked with a computer or cloud badge where ambiguity matters. Commands sent from a pane inherit that pane's location. From a shell outside atrium, use the global --location <name> flag; atrium fails if that location cannot be resolved rather than silently running the command locally.

atrium --location build-box workspace list
atrium --location build-box task create --title "Run integration tests" --source "user:me"
atrium agent list --all-locations
atrium agent message <agent-id>@build-box "Please post a summary" --no-reply

Remote task references use the same qualifier: ATR-42@build-box.

Disconnects and recovery

If a box becomes unreachable, atrium keeps the last known state visible and marks that location unreachable — read-only. It does not redirect writes to your Mac or create a divergent local copy. When SSH returns, the client reconnects to the same daemon, PTYs, sessions, and scrollback without relaunching them.

The remote daemon also owns its scheduler. A recurring task assigned to that location can fire while the macOS app is closed, as long as the box and daemon are running.

Manage a location

Open Settings → Locations, then select a location to inspect:

• Connection identity, operating system, last seen time, and health.
• Tool and daemon version state; Update daemon safely re-runs provisioning.
• Agent credentials, publishing access, and provider accounts for that box.
• Forwarded ports and paired devices.
• Access revocation and removal.

Removing a location unregisters it from this Mac. It deliberately leaves the machine, repositories, and remote data untouched. To revoke one capability without removing the box, use the matching control in Settings or atrium remote revoke.

Trust boundary

Treat a location like any machine on which you run developer tools: its users and administrators can read the repositories, processes, credentials, and atrium data stored there. Only connect boxes you trust, review credential-forwarding prompts, and revoke lost devices from the location detail.

Computer use is separate. Connecting a location does not grant an agent permission to drive desktop applications; that capability has its own allowlist, protected-surface checks, and emergency stop. See Computer use.