SSH & Remote Runtimes
An independent runtime lets selected agents continue when Locus closes or disconnects. You can run it on this Mac or deploy a reviewed project snapshot to a machine you own over SSH. Ordinary agents keep their existing lifecycle unless you opt them in.
Independent-runtime controls were introduced in 2.8. The upcoming 3.0 release adds portable package builds and safer updates. Portable archives remain candidate artifacts, with live SSH, signed desktop registration, login/reboot, connector, and provider validation still required before production readiness. A passing package smoke test is not a verified live deployment.
Enable this Mac
- In direct-download, wallet-free Locus, open Settings → Runtimes.
- Select Enable independent runtime while existing work is idle. Review the background-service status and any macOS registration request. Open macOS Login Items opens the relevant system setting.
- Open a chat to start its runtime worker. Under Agents on this runtime, enable Keep running when Locus closes for each worker that should continue.
- Use its Pause, Resume, or Stop control to supervise execution. Stop runtime pauses the runtime's work while preserving saved progress.
The Mac must remain awake and logged in. The App Store and LocusX editions do not install this independent helper. Installing the service alone does not opt every agent into continued execution; automation continuation follows its owning agent's explicit setting.
The runtime owns workers, schedules, events, and durable decisions independently of the window. Browser, Computer Control, and other native operations still need Locus's desktop broker. They wait with a visible reason while Locus is unavailable. Closing the application cannot supply an approval or answer a required question.
Prepare an SSH host
| Target | Requirements |
|---|---|
| Linux x86-64 or ARM64 | glibc 2.28 or newer, a working systemd user session, and SSH access. User lingering is required for continuation after SSH logout. |
| Apple Silicon Mac | macOS 14 or later, an active graphical login, an awake machine, and SSH access. |
| Initial setup on either host | Python 3.10 or newer for installation. The installed service uses its bundled Python. |
Use an SSH configuration or host you trust and have already authorized. Locus validates host keys strictly and carries its loopback-only control connection through an authenticated SSH tunnel. A new or changed key must be resolved deliberately; do not disable host verification to work around a mismatch.
Under Settings → Runtimes → Remote runtimes, enter the host and select Validate host. The result identifies the platform and requirements. Choose the matching runtime archive and its SHA-256, then select Install runtime. Choose a package from a trusted build or distribution; a checksum verifies integrity, not the publisher's identity.
Candidate builds target linux-x86_64, linux-arm64, and macos-arm64 separately. A Mac archive cannot run on Linux. See Build & Test for source build details.
Deploy an agent
- On the validated runtime, choose Deploy agent.
- Review the Project snapshot. Select the files to transfer and inspect exclusions for secrets, ignored files, caches, and unsafe paths. The snapshot can include current local edits.
- Select any Approved project checks to include. Only the chosen approved versions are transferred.
- Choose the model account and permission mode. Select only the connector credentials required for this work.
- Enter the work request, choose Keep running when Locus closes if wanted, and optionally enable Repeat every hour.
- Choose Deploy and verify readiness. Review account and worker status before relying on execution.
The deployment reviews a fixed snapshot. Changes after review require a new review. Upload and schedule retries reconcile a stable deployment identity rather than duplicating work; an interrupted upload can offer Recover deployment.
Accounts belong to the destination
Only the selected account and connectors are provisioned. API and connector credentials travel through the authenticated tunnel into the runtime's separate private store; they are not embedded in the project snapshot or command arguments.
Subscription accounts sign in independently on the host. Use Sign in on remote runtime, or Use browser login through SSH when available, and follow the displayed flow. Each account has a separate credential home. Locus does not copy a local ChatGPT login into the destination or fall back to an API key.
The standard candidate builder includes the ChatGPT helper. Claude plan support requires a package explicitly built with the optional verified Claude helper; a package without it does not advertise that capability. Claude plan remains a preview with the separate limitations described in Hosted & Custom Models.
Monitor and retrieve work
Health and approvals shows the runtime version, package, account readiness, workers, waiting reasons, and current decisions. You can answer supported questions, allow a tool once, decline, pause an agent, resume it, or stop it. Native operations and specialized reviews retain their own controls.
Choose Retrieve result to inspect returned files, saved runs, verification evidence, and usage. Select the changes you want and choose Apply selected changes. Locus checks the original local baseline before applying; later local edits can conflict and are not silently overwritten. Retrieval does not automatically apply files, commit, or merge them.
If a command or external action has an uncertain outcome, inspect saved files and activity before using Keep saved work and allow new tasks. The uncertain request is not automatically replayed. Disconnecting and reconnecting restores durable events and pending decisions without treating a stale decision as current approval.
Pause, update, or retire a host
Use Pause runtime to pause work, Resume scheduling to resume scheduling, and Stop service or Start service to control the remote service. Updates refuse active or draining work. Pause and drain first.
During installation, the runtime blocks new work, backs up its databases, and checks candidate startup before activating the package. Failed startup restores the previous service and databases. Interrupted updates retain a recovery journal; successful updates keep the previous package and database backups.
Remove connection removes Locus's connection record. It preserves remote work, files, and credentials. Stop the service and remove retained host data deliberately when retiring it; revoke provider credentials separately where appropriate.
The selected host and its user account are part of the trust boundary. Its owner, or another process with equivalent account access, can read credentials provisioned there. See Credentials & Local Data.