Skip to main content

Remote machines

The server sandbox keeps agents safely contained. Sometimes, though, you want the opposite: an agent with full access to a real machine — to work with local files, drive a desktop app, use a browser with your saved logins, or administer a server. Remote machines are how you do that, and you still chat with and watch the agent from the same dashboard.

What a remote machine is​

You run the same agents on a computer you own — a laptop, a workstation, a server — where the agent works natively with that machine's files, network, and installed tools. To you it behaves just like a server-side agent: same chat, same live streaming, same dashboard. The difference is where it runs and how much it can reach.

A deliberate trade-off

An agent on a remote machine is not kernel-sandboxed — it runs as your operating-system user on that machine. That's the point: you've chosen full control on hardware you trust. The boundary here is the agent's role and access policy, not a sandbox. Only pair machines you trust, the same way you'd only run a tool on your own computer.

Pairing a machine​

Pairing is quick and needs no open ports:

  1. From the dashboard — Admin → Remote Machines for shared machines, or User Settings → Remote Machines for your own — start pairing and pick the machine's operating system.
  2. OtoDock gives you a one-line install command for Linux, macOS, or Windows.
  3. Run it on the machine. It installs a small background app — the satellite — and connects back to OtoDock.

The connection is outbound only — the machine reaches out to OtoDock, so there's no inbound port to open and no public IP required. The pairing code is short-lived and single-use.

Two kinds of machine​

  • Shared (admin-paired) — platform infrastructure, paired by an admin. An admin assigns agents to it and can make it an agent's default execution target — the right shape for an agent that administers that server, or a capable machine the agent's work should live on. Only the agent's managers run their chats on a shared machine. Viewers, contributors and editors keep working on the server, where the sandbox keeps each of them to the files their role allows.
  • Personal (user-paired) — your own laptop or workstation, paired for yourself. Run any of your agents there when you want them next to your local files, apps, and network. Only your own sessions run on it.

Either way, you choose which agents run on which machine with a simple per-agent assignment.

Prefer that agents only ever run on machines the team manages? An admin can turn personal pairing off platform-wide (Setup → System Settings) — existing personal machines disconnect and stay paused until it's re-enabled.

Access levels​

You control how much of the machine an agent can reach:

  • Home-only (default) — agents are limited to your home folder and the agent's own files. This is a guardrail, not a sandbox: the agent still runs as your OS user.
  • Full filesystem access (opt-in) — agents can touch anything your OS user can, except the machine's own OtoDock folder (see below). A simple toggle, off by default.
  • Device control (opt-in, per capability) — three separate grants on the machine's card: computer control (mouse, keyboard & screen), browser control (a real browser on the machine: a dedicated per-agent profile, or your own; see below), and app connectors (controlling a running desktop app). Each is off by default and turned on individually, with a clear confirmation, and takes effect — or revokes — live.

Browser control: a dedicated profile, or your own browser​

With browser control granted, the agent drives a real browser on the machine. By default that's a dedicated profile per agent: a persistent browser window of its own that stays logged in to whatever you sign it into. The machine card's Browser mode offers a second choice, My own browser. The agent then works inside the Chrome, Edge or Brave you are already signed into, in a tab group of its own, so it can use your accounts without you logging in anywhere twice.

It works through the Playwright Extension, linked from the card. Install it in that browser, then either click Allow in the extension when a session connects, or paste the extension's token on the machine card so sessions connect on their own. Unattended sessions such as scheduled tasks need the token, since nobody is there to click. The token is stored encrypted and never shown again; clearing it puts sessions back on the click-to-connect path.

A few things to know:

  • Your logins, cookies and open tabs are reachable to the agent. That's the point, and the reason it's a per-machine choice with a confirmation. Only the machine's owner can switch a personal machine to its own browser; admins decide for shared machines.
  • The agent sees only its own tab group (tabs you drag into it included), never your other tabs, and closing its session leaves those tabs open in your browser.
  • The browser needn't be open, since the agent starts it if it isn't, but the machine needs a desktop session. Firefox and Safari can't be driven this way; a machine without a Chromium-based browser keeps the dedicated profile.
  • Changes take effect for sessions that start afterwards; running ones keep the browser they started with.
  • The agent's tab group is named after it, and connecting brings its tab to the front. You can drag the group into a window of its own and keep working in yours.
  • To have the agent work on a page you already have open, drag that tab into its group.
  • When a session can't connect, the agent tells you why: the extension isn't installed, its token has gone stale (make a new one on the extension's page and save it on the machine card), or it's waiting for you to click Allow.

Even with full access, an agent runs as you — it gains no elevated privileges — and OtoDock's access policy keeps sensitive material like SSH keys and stored credentials off-limits. Whatever the access level, agents also can't reach the machine's own OtoDock folder (its settings and machine key, the browser profiles and the installed tools) or the folders of other agents on that machine. Each agent reaches only its own.

Secrets a session genuinely needs — SSH keys the agent has been granted, integration tokens — are delivered to the machine just for that session and wiped when it ends; nothing sensitive is stored on the machine between sessions.

Files stay in sync​

The agent's files are kept in sync both ways between OtoDock and the machine, automatically. Results show up in the dashboard as the agent works, and files you add from the dashboard appear on the machine — so collaborating with a remote agent feels just like a server-side one.

Exactly the agent's own folders are mirrored, and nothing else on the machine:

  • workspace/ — the agent's shared team workspace
  • knowledge/ — the reference library, attached shared libraries included
  • config/ — persona and context files
  • users/<you>/ — your private space: your workspace, your context and your own checks

(Depending on the agent's mode, some of these may not exist.) On an admin-paired machine all of them sync both ways — it hosts every user of the agent. On a personal machine, sync follows your role on the agent. Your private folders always sync both ways. The shared folders come down to the machine so the agent can read them, but changes made there are sent back only where your role lets you edit: the shared workspace if you're a contributor, editor or manager, and knowledge and config/ if you're a manager (config/ isn't placed on the machine at all otherwise). Pairing a laptop never copies anything outside these folders.

The agent's tools run on the machine too, installed next to the session — only Docker-based tools stay on the OtoDock server, reached over the platform connection.

A few details worth knowing:

  • Uploads are chunked and tracked. Files up to 1 GB (admin-tunable) upload with live progress, and the workspace's transfer popup shows per-machine sync progress until a file has actually arrived everywhere.
  • Build output stays put. Generated build directories (a Rust target/, a Gradle build/, and the like) are detected and skipped automatically, so a compile on your workstation doesn't sync thousands of regenerable files back to the platform. Detection is conservative: a folder is only skipped when its contents prove it's generated, never on the name alone.
  • Nothing is lost to conflicts. The newest edit wins, and the losing version of a genuine conflict goes to the workspace's Recover bin (kept 7 days) with a notification pointing you at it. A machine's missing files never delete platform data; a wiped machine is simply re-synced.

Which agents can run remotely​

  • Claude Code and Codex run on remote machines, including as a live interactive terminal. A message you type while a remote agent works reaches it mid-turn, just as on the server.
  • The direct engine always runs on the server (there's no process to relocate).
  • A shared (team-wide) agent can't be pinned to a personal machine — it belongs on a shared one.

Cross-platform​

Linux, macOS, and Windows are all supported. On Windows there's a system-tray app to pause, resume, remove the machine, open the dashboard, or view logs.

The machine card​

Each paired machine gets a card in the dashboard showing its live status, OS and hardware, active sessions and capacity, and the Claude and Codex CLI versions the machine actually runs, highlighted when they drift from the platform's pinned versions. Admins can cap a machine's concurrent sessions, or leave it on the satellite's own automatic sizing. At the ceiling, the platform quietly closes the machine's most-idle sessions to make room (never one mid-turn), and evicted conversations resume with full context on their next message.

Staying online (and offline)​

The dashboard shows each machine's status. What happens when a machine goes offline is set by two admin toggles (Setup → System Settings); here are their defaults:

  • A personal machine that's offline → the session falls back to the agent's usual home — its admin-assigned machine if it has one online, otherwise the server — with a brief banner so you know. (On by default; an admin can switch it off so the session waits for the machine instead of moving.)
  • A shared, admin-assigned machine that's offline → work for that agent pauses with a clear message and resumes when the machine returns — it won't silently move to the server, since admin assignments often imply data-residency intent. (Off by default; an admin can turn on fall-back-to-server if they prefer.)

Updates and removal​

The remote agent software updates itself automatically (admins can switch a machine to manual updates). Removing a machine from the dashboard triggers a clean uninstall on the machine itself — the agent software and synced files are removed. An admin can remove any machine from Admin → Remote Machines, including a user's personal one, and its owner gets a notification.

Next steps​