Remote Build

Build on another machine while using Atmos from your laptop or browser.

Remote build means your Atmos UI runs on one device while the project runtime runs on a registered Atmos Computer.

Use this workflow when a different machine should own the repositories, terminals, agents, workspace state, and build output.

Overview

After you connect to an Atmos Computer:

  • workspaces, branches, terminals, and agent history belong to that computer;
  • your laptop or browser acts as the client;
  • the CLI can resolve the same active computer through ~/.atmos/client-session.json;
  • if no remote client session exists, the CLI falls back to the local runtime manifest.

To return to the runtime on the machine in front of you, choose Use locally.

Step 1: Create an Access Key or Access Token

  1. Open Settings → Atmos Computer.
  2. Find the Access Key area.
  3. Generate a new key or paste one you already trust.
  4. Save it on the device where you manage computers.
  5. Copy it immediately if you need to register another host.

Treat the access key like a password.

The mobile app uses the label Access Token for the same credential.

The Mobile App is currently in development and temporarily unavailable.

Step 2: Register A Computer

Current Machine

  1. Make sure Atmos is running on this computer.
  2. Open Settings → Atmos Computer → This Computer.
  3. Enable registration.
  4. Wait for this host to appear under My Computers.

Another Machine

  1. Install Atmos Desktop or the local web runtime on the machine that should run the work.
  2. Create a registration code from the device where your access key is saved.
  3. Run the shown CLI command on the target machine.
  4. Confirm the computer appears as Online.

Registration codes are short-lived and single-use. Generate a new one if it expires.

The generated command usually calls:

atmos computer start --token <registration_code> --daemon

For private Relay, the command may also include --relay and --relay-secret-key.

Step 3: Connect

  1. Open Settings → Atmos Computer → My Computers.
  2. Select an online computer.
  3. Click Connect.
  4. Wait for the UI to reload against that computer.

Offline computers remain visible but cannot be selected until they reconnect.

Step 4: Work Normally

Once connected, use the same Atmos workflows:

CLI commands use this resolution order:

SettingResolution order
API URL--api-url, ATMOS_API_URL, active client-session.json, runtime_manifest.json
API token--api-token, ATMOS_API_TOKEN, ATMOS_LOCAL_TOKEN, active client-session gateway token

Security Notes

TopicWhat to know
Access keyAnyone with the key can manage your registered computers. Store it carefully.
Registration codesShort-lived and one-time. Remove unused codes.
Relay secretsPrivate Relay deployments may require a Relay secret in addition to the Access Key.
SessionsConnect sessions expire. Reconnect from My Computers when needed.
RevocationRemove a computer from My Computers when it should no longer be available.

On this page

OverviewStep 1: Create an Access Key or Access TokenStep 2: Register A ComputerCurrent MachineAnother MachineStep 3: ConnectStep 4: Work NormallySecurity NotesRelated