Remotes

A remote is a machine you connect to inference with belt remote start. It hosts agent harnesses and, when you opt in, runs agent sessions or shell commands the platform dispatches.

The daemon connects outbound to inference over an authenticated WebSocket. Nothing listens on your machine, and the daemon runs only what the server sends.

A managed sandbox is a remote the platform runs for you: a VM that starts belt and registers the same way.

In the workspace

After you run belt remote, open Resources → Remotes in the sidebar (/remotes) to see connection status, harness profiles, and whether exec is enabled on each host.

Select a machine to open its page:

• Agents — one card per harness profile on the machine. Launch asks for the folder the harness should work in and opens a chat with the harness-backed agent for that profile. A card cannot launch while the machine is offline, the daemon was started without --agents, the harness is signed out or too old, or the profile is busy.
• Machine — belt version, hostname, OS, CPU, whether agent sessions and command execution are on, and last seen.
• Rules — allow, ask, and deny rows for commands, workspace folders, and harness tools on this machine. They apply to every remote_exec dispatch and harness call on the remote, and only the remote's owner or someone with a write share can change them (see Agent and remote permission rules).
• Sessions on this machine — harness sessions inference started and sessions opened locally. Continue on an idle session reopens it in a chat.

When to use a remote

A remote is not a private inference engine. Engines run GPU/CPU workloads from the task queue. Remotes host harnesses and optional shell execution on a machine you control. See Private workers for compute on your hardware.

Security model

• Outbound only. The daemon dials wss://api.inference.sh/ws/remotes/{id} with your API key. No inbound ports are opened.
• Your OS user. Commands and harness sessions run as the user who started belt remote start. That user is the blast radius.
• Exec is opt-in. Command execution is disabled unless you start the daemon with --exec. Without it the daemon refuses remote_exec_start frames, and the API refuses the dispatch with 403 exec_disabled.
• Agent sessions are opt-in. Inference may drive harness sessions (Claude Code, Codex, Cursor, and similar) on your machine only when you start the daemon with --agents. Without it the daemon refuses remote_session_open frames, ignores other session frames, and answers opens with agent sessions are disabled on this remote (start it with --agents).
• Permissions stay with you. The daemon never auto-approves harness tool calls locally. Approval requests go through inference.sh; a person allows or denies them, or has already chosen always allow for that tool in the chat, in which case the API answers the harness without parking the run. See Remote harness runs.
• Destructive CLI gate. belt remote exec prompts for confirmation, or requires --yes in non-interactive mode.
• Yours unless you share it. Teammates can see your remote. Running commands, opening harness sessions and placing agents on it needs you (its owner) or a use or write share. Changing it, deleting it, editing its policy rules and managing its shares needs you or a write share. Anyone else who can see it gets 403 ("this remote is another person's machine and is not shared with you for this"); admins do not bypass this. Heartbeats and the daemon connection are yours alone. See Visibility and sharing. Exec runs and their output are visible only to the person who started them and to the remote's owner; environment variable values are never returned by the API.
• Policy paths follow symlinks (belt v1.19.13+). When workspace policy evaluates remote exec, workspace, or harness paths, the API asks a connected daemon with --exec or --agents to resolve absolute paths through symlinks on the host. Allow rules must match a path both as written and where it leads, so a symlink cannot bypass a rule on the literal path. If the daemon is too old, offline, or does not answer within a few seconds, paths are judged as written; an otherwise-allowing rule may surface as a person approval instead.
• ~ paths use the daemon's home. On registration the daemon may send home (the account's absolute home directory). Workspace rules and calls that name ~/… resolve against that path on the machine before symlink resolution. When home is missing (older daemon), ~ paths are judged as written.

Run the daemon under a dedicated user or inside a container if you need a smaller blast radius.

Connect a machine

Prerequisites

• Belt CLI installed and logged in (belt login)
• An API key or session with the remotes:write scope. The standard key preset includes it.

Start the daemon

1belt remote start2belt remote start --name "work-laptop"    # custom display name; later starts keep it3belt remote start --exec                  # allow command execution on this host4belt remote start --agents                # allow harness agent sessions on this host5belt remote start --exec --agents         # both exec and harness sessions

On start, belt:

1. Creates or loads a machine identity key (remote_ed25519) in ~/.inferencesh/. When BELT_CONFIG_DIR is set, the key lives in that directory instead. The private key stays on the machine; only the public key is sent.
2. Probes the machine for installed agent harnesses (see Harness discovery). The CLI shows discovering agent harnesses... as its own step before registration.
3. Registers the remote with POST /remotes, sending the name (default: hostname), public key, belt version, system info, the daemon account's home directory (used to expand ~ in workspace rules; stored, not returned on remote API responses), probe results, and opt-in flags (exec_enabled, agents_enabled)
4. Connects to the remote WebSocket and sends a heartbeat every 5 seconds (every third beat also carries a fresh system_info snapshot with live CPU, RAM, and home-disk usage)

Foreground vs background. With no flags, belt remote start holds the terminal open until you stop it:

Detaching is only available on an interactive terminal (not when stdin is piped or in CI). Only one belt remote start may run per machine at a time (foreground or detached), keyed on the machine identity in ~/.inferencesh/. That instance holds a lock that belt remote status and belt remote stop use — including foreground sessions, which status labels mode: foreground, in the terminal that started it instead of a log file path.

A second belt remote start with the same --exec and --agents flags exits with a remote is already running on this machine (pid …); run belt remote stop or disconnect that session first. If you start again with different --exec or --agents values, belt offers to restart the running daemon with the new permissions (stopping ends any harness agent sessions on that machine, so it asks for confirmation). Decline the prompt or run in non-interactive mode without --yes, and belt leaves the running remote unchanged — use belt remote stop, then start again with the flags you want. Press d to detach: belt closes the foreground connection, releases the lock, and starts a background daemon with the same flags. If agent sessions are running in the foreground process, they are its children and would end on detach; belt asks you to press d a second time to confirm.

Flags such as --exec, --agents, and --name belong to belt remote start, not the bare belt remote group. Typing belt remote --exec prints an error that names belt remote start --exec instead of a generic unknown-flag message.

To start in the background immediately:

1belt remote start --detach    # or -d2belt remote status            # pid, remote id, connection state and how long it has held3belt remote logs -f           # follow the daemon log4belt remote stop              # stop the running remote (foreground or background)

Logging. Foreground belt remote start shows harness discovery and registration progress in the terminal and prints connection warnings there. Info-level WebSocket diagnostics are suppressed so they do not interleave with the spinner. When a harness session closes with an error, the daemon logs a warning such as session for chat <id> closed: <reason> — the same reason inference shows on the failed chat turn. A detached daemon writes info and warn logs to the file path shown by belt remote status; use belt remote logs or belt remote logs -f to read them.

With --exec, registration sends exec_enabled: true and the daemon accepts command-dispatch frames. With --agents, registration sends agents_enabled: true and the daemon hosts harness sessions the API opens over the socket (remote_session_* frames). Without each flag, the corresponding frames are refused on the host. Exec and agent sessions are independent opt-ins — you can enable either or both.

Detached daemon. belt remote start --detach keeps the socket open in the background. Use belt remote status, belt remote logs -f, and belt remote stop to manage it. belt remote list shows remotes registered to your team in the API.

Connection state. belt remote status follows the socket for as long as the daemon runs and shows the belt release the daemon runs (belt v1.28.6 and later). state is connected or retrying, with how long it has held, for example retrying (for 54m12s). While it is retrying, reason carries the server's answer to the last attempt (server answered 401 Unauthorized) or the transport error, and hint names the fix when retrying alone will not get past it. The daemon logs the same lines on every change.

Logins. The daemon reads belt's credential again before every connection attempt, so it outlives the login it was started with. When a session expires or is replaced, the next reconnect is refused with 401; run belt login and the daemon reconnects with the new login on its next attempt, within 30 seconds, without a restart. The team does not follow: the remote stays in the team that was active when it started, and belt auth switch in another terminal does not move it. On a server, an API key scoped to remotes:read and remotes:write (belt login --key-stdin, or INFERENCE_API_KEY in the daemon's environment) is not tied to a login session's lifetime.

With --agents, registration sends agents_enabled: true and the platform can list harness sessions on the machine and open chats that run the harness in a folder you choose. When a profile reports capabilities.approvals: true, risky tool calls wait for your approval in the workspace; harnesses with approvals: false (Pi today) run tools without asking. Without --agents, the status output shows agents: disabled.

Start at boot

A remote started with belt remote start does not come back after a reboot. belt remote enable installs it as a service instead: a systemd user unit on Linux, a LaunchAgent on macOS.

1belt remote enable --name build-box --exec --agents   # same flags as start2belt remote status                                     # mode: service, started at boot (login on macOS)3belt remote disable                                    # remove the service

enable writes a systemd user unit (~/.config/systemd/user/belt-remote.service), enables it, and starts it. No root is needed: the service runs as you, with your login and the PATH you enabled it from, so harness discovery finds the same CLIs your shell does. If a remote is already running on the machine, enable asks before restarting it as the service, because stopping it ends its agent sessions; decline and the service takes over at the next boot.

On macOS, enable writes ~/Library/LaunchAgents/sh.inference.belt-remote.plist and loads it with launchctl bootstrap. Running enable again boots out the previous agent and waits up to 30 seconds for launchd to unload it before bootstrapping, so bootstrap does not fail with 5: Input/output error (belt v1.28.6 and later). It behaves as on Linux, with one difference: a LaunchAgent starts when you log in, so a Mac comes back on its own after a reboot only with automatic login turned on (System Settings > Users & Groups). belt remote stop stops it until the next login, and disable marks it disabled and removes the plist.

Stopping or restarting the service ends the commands and agent sessions the daemon was running. A process a command deliberately left behind (a server started with nohup, for example) is not killed, the same as with a remote started by hand.

List and remove remotes

Account-level commands (run from any machine where you are logged in):

1belt remote list              # name, host, id, status, exec, last seen, belt version2belt remote rm <id>...        # remove stale rows from your account3belt remote rm <id> --yes     # skip the confirmation prompt

belt remote list marks the row for this machine when a local daemon is running. After a machine has been offline for more than a week, list prints a hint to remove it with belt remote rm.

belt remote rm calls DELETE /remotes/{id}. Use it for retired or reinstalled hosts that left an old registration behind. It is destructive (confirmation prompt, --yes in non-interactive mode). Removing a row does not stop a daemon that is still running on that host — run belt remote stop there first. If a stopped daemon starts again later, registration creates a new remote id (same machine key, fresh account row).

Update belt on a remote

Update a connected remote to the latest belt from any machine, or with update on the remote's page:

1belt remote update <id>

The remote stops taking new work and waits up to 10 minutes for running commands and agent turns to finish. It installs the release while still connected, then restarts the way it was started. It keeps its name and settings and reconnects on the new version. Idle agent sessions and open terminals end with the restart. If the install fails, the remote goes back to work on the version it has.

How it restarts depends on the platform:

A remote cannot update itself when belt was installed by a package manager (Homebrew, Scoop), or when the user it runs as cannot write to belt's directory. The answer says what to do on the machine instead.

When belt is updated on the machine

A remote also follows a belt installed over the one it runs, whatever installed it: belt update, belt's own auto-update, the install script or a package manager. It checks once a minute. Nobody asked for this restart, so it ends nothing: it waits until no command, agent turn or terminal is running, for as long as that takes, and keeps taking work meanwhile. Before it switches, it runs belt --version on the new file (no network); a file that does not run, or reports the release already running, is ignored. Then it restarts onto the installed belt the same way as above. Idle agent sessions resume on the next message.

belt update says when the remote on the machine will move. A remote started before belt v1.28.6 does not follow updates; belt update prints the command that restarts it once.

Tags

Tags group remotes for workspace policy: a rule written for tag:prod applies to every machine that carries the prod tag, including machines you add later. Tags are lowercase letters, digits, -, _, or . (up to 40 characters each, at most 20 per remote). The API stores them normalized (trimmed, lowercased, deduplicated).

Changing tags needs manage_policy on the remote's workspace, because tags decide which policy rules apply to a machine. Unlike other remote writes, it does not require owning the remote.

1belt remote tag <id>                  # show tags2belt remote tag <id> prod eu-west     # add tags (merged with existing)3belt remote tag <id> --rm eu-west     # remove tags

With --json, it prints the tag list after any changes. The REST equivalent is PUT /remotes/{id}/tags.

System info

Registration and periodic heartbeats include a best-effort snapshot of the host in system_info (collected with gopsutil, the same approach private engines use):

A probe that fails reports a zero value. Registration does not fail because of it.

While the daemon stays connected, every third WebSocket heartbeat (~15 seconds at the default 5 second interval) carries an updated system_info. The API stores each snapshot on the remote, so GET /remotes/{id} and the workspace remote page can show live load the way engine cards do. The first heartbeat after connect omits system_info because registration already sent one; CPU usage on later snapshots reflects load since the previous collection. The HTTP heartbeat endpoint does not carry system_info.

Harness discovery

The daemon probes the host using the agentprotocol harness registry and sends the results in the harnesses field of POST /remotes. Each entry describes one registry harness whose binary was resolved on the machine (PATH, known install paths, or global package lists):

Probes run in parallel for every registry harness. The daemon checks config directories, PATH, known install locations (for example ~/.local/bin), and a cached global npm list -g (10 second timeout for the whole list). When a binary is found, it runs <command> --version with a 3 second timeout per harness. A stalled or slow binary leaves version empty instead of blocking registration. A machine with several CLIs usually finishes discovering agent harnesses... in about a second before registering remote... appears.

Discovery uses the shared harness registry in agentprotocol (harness.DetectInstalled). Every registry entry with a resolvable binary on the host is reported; kind is the registry id (for example claude, codex, gemini, cursor). Examples:

logged_in means the harness looks configured on this machine (Configured() in the registry). It is not proof the harness can serve a run. Discovery never reads credential files or transmits tokens.

Account and plan limits. Registration does not wait for usage probes. Once connected, the daemon rediscovers its harnesses and runs each one's usage probe to read who it is signed in as and its plan's rate-limit windows (in parallel, 60 second timeout each). It sends the result on a heartbeat right after it connects and then every 5 minutes. A probe that reports authenticated or unauthenticated also sets logged_in. A failed probe keeps the last good windows. A running session can report newer numbers between probes.

The API exposes harnesses as profiles on each remote (harness_kind, command, status, capabilities, account, limits). On every POST /remotes the server reconciles the harnesses payload into profiles, one per harness kind. A harness with logged_in: true becomes idle; without it the profile is unavailable. If a harness disappears from the host, its profile stays and becomes unavailable.

capabilities on a profile mirror what the daemon reported at registration. The API branches on these flags instead of hard-coding harness names:

capabilities is omitted on older daemons or harnesses the session host cannot drive (no session driver in the registry); treat missing values as false.

Registration keys on the machine's public_key within your active team (from your API key or belt auth switch). Restarting belt remote start on the same host updates that team's remote and its profiles; it does not create a duplicate. After you switch teams, the same machine gets a separate remote row for the new team. Remotes for other teams remain in the list until heartbeats go stale and the platform marks them disconnected, then stopped.

Agent harness sessions

When --agents is enabled, the daemon hosts one harness process per chat the API opens on this machine. Inference owns the conversation, run lifecycle, and every permission decision; the daemon launches the harness, forwards events, and applies prompts, interrupts, and permission resolves the API sends.

How harnesses are launched. The session host picks a driver from the agentprotocol registry for each harness id:

Belt passes only the resolved binary path. It does not add registry auto-approve flags, pinned models, or endpoints. Tool permission prompts always reach inference so a person can allow or deny them. The harness uses your vendor login from its own config; credentials never pass through the daemon.

• One chat, one session. Re-opening the same chat attaches to the existing process instead of starting a second writer.
• Open before launch. remote_session_open reserves the chat slot before remote_session_opened is sent; the harness starts in the background so a prompt right behind the open waits on the session instead of racing the launch.
• Event position on open. remote_session_opened includes seq, the last event number the session has produced (0 for a fresh process). Callers use it to tell a restarted harness from a replay after reconnect.
• Replay buffer. While the socket is down, the daemon keeps a bounded buffer of session events so the API can replay after reconnect.
• Host limits. The daemon caps concurrent harness sessions (default 8) even when a profile allows more.
• Local session index. Call GET /remotes/{id}/sessions (or the WebSocket remote_sessions_list frame) to see harness sessions on disk — metadata only: id, title, cwd, last updated, and whether a process currently holds the session. The daemon returns at most 500 sessions, newest first. When liveness is inferred rather than proven, live.heuristic is true (the workspace remote page marks those states with ? in the UI).
• Closing sessions. When inference sends remote_session_close, or you stop the daemon (Ctrl-C, belt remote stop, or process exit), the daemon asks the harness to end. If the process is still running after a short grace period, belt kills it when the session driver supports that, so a wedged agent cannot hold a slot or block shutdown. Stopping the daemon ends all hosted sessions in parallel. ACP-backed harnesses also report closed when their CLI process exits on its own.

Harnesses without a session driver in the agentprotocol registry are not offered for hosted sessions (capabilities is omitted at registration).

Questions from the harness

When a harness asks you a question instead of asking for permission, the chat shows it as a form: one choice (or several) per question, plus a field for an answer of your own. Submit, decline or cancel it like an MCP server's input request. Your answer goes back to the harness in its own format. No "always allow" rule or "allow every tool" setting answers a question for you (belt v1.28.4+).

Refusing the interrupt (instead of answering the form) tells the harness you declined.

Background work

Some harnesses leave a command or a watch running while their turn goes on (Grok's background commands and monitors). The tool call that starts it completes at once. When the work ends, the chat shows a line saying what ended and how, for example `make build` failed (exit 2).

If the harness then starts a turn of its own about it, that turn is a run of its own in the chat, answering that line, even though nobody sent a message. While your own run is still going, the harness's work is part of that run (belt v1.28.4+).

Platform catalog tools

When a profile reports capabilities.tools: true, the API gives the harness the three meta tools loop agents enable with internal_tools.meta: search_tools, list_tools and execute_tool. The harness keeps its own tools on the machine; these three reach the apps, agents, skills and knowledge in your workspace.

remote_session_open carries the tool definitions in tools. The daemon does not run them. When the harness calls one, the daemon sends remote_session_tool_call (call_id, name, arguments, run_id, optional tool_invocation_id). The API records the call on the chat as type: internal, runs it as that run, with lifecycle gates and tool approval as for any loop tool, and answers with remote_session_tool_result (text, is_error). Approvals for these calls are not sent with remote_session_resolve, which is only for tools the harness runs on your machine. A tool name outside the three is refused.

Profiles without capabilities.tools get no tools on open, and the harness sees only its own tools.

Wire format: Remotes API — WebSocket protocol.

Attachments

Images and files you attach to a message in a harness chat go to the harness with the prompt (belt v1.21.0+).

1. The API sends the message's text and its files together in remote_session_prompt.
2. The daemon downloads each file into a temporary folder for that chat on your machine (https only, up to 50 MB and 60 seconds per file) and hands the harness a local path. The folder is deleted when the chat's session ends.
3. The harness gets each image as an image when it supports them (capabilities.images). Every other file, and every image for a harness without image support, is named in the prompt by its local path, so the harness can open it with its own tools.

Some harnesses resize or re-encode an image before sending it to their model (OMP scales small images up, for example).

If a download fails, the harness gets the file's URL instead of a path. A daemon older than belt v1.21.0 does not report capabilities.files; for those, the API writes the files' URLs into the prompt text, so the harness still sees them. Update belt on the machine to get attachments as files.

Wire format: Remotes API — WebSocket protocol.

Profile-backed agent chats

When you start the daemon with --agents, registration only exposes harness profiles on the remote. Workspace agents are created when you launch a harness from the app or API — not when the machine connects — so connecting a laptop does not fill your agent list.

Launch from the workspace. Pick a remote, harness profile, and folder; the UI calls POST /remotes/{id}/sessions and opens the returned chat. Optionally pick an existing harness session to resume (from sessions listed for that folder).

Launch from the API. Same endpoint — profile_id, work_dir, and optional resume_session_id. See Launch harness chat.

The first launch for a profile creates one harness agent and reuses it afterward:

Each chat carries the folder in work_dir and optional harness_session_id when you resume. Harness sessions are folder-bound; the agent record is not.

Send messages with POST /agents/run, POST /chats/{id}/messages, the SDK, or the workspace. The API opens the harness session on your remote in that folder, streams replies into the chat, forwards permission prompts as approval interrupts, and records harness-side tool calls without re-running them on inference.sh. Harnesses that report capabilities.steer: true (for example Claude Code and Codex) accept follow-up user messages during an in-progress turn; others queue them for the next turn.

Requirements: the remote must stay connected with --agents, the profile must be idle with valid capabilities, and the harness must remain logged in on the host. See Agents API — Remote harness runs for run lifecycle, queueing, stop, and error strings.

Disconnect. If the daemon drops while a harness run is active, the run fails with the remote disconnected and is not retried. Restart belt remote start --agents and send a new message to continue the conversation (the chat keeps harness_session_id when the harness can resume the session).

Run a command

Dispatch a command to a connected remote and stream its output:

1belt remote exec <remote-id> -- ls -la2belt remote exec <remote-id> -- bash -c "echo hi && uname -a"

The remote must have been started with belt remote start --exec. Otherwise the API returns 403 exec_disabled.

belt remote exec is marked destructive and prompts for confirmation before dispatching. In CI or scripts, pass --yes / -y, or call the REST API directly.

Exit behavior. belt exits with the remote command's exit code when the run status is exited. Runs that end as killed or denied print an error and exit 1.

Stopping a command. Pressing Ctrl-C in belt remote exec kills the command on the remote and waits for the run to end; a second Ctrl-C exits without waiting. To kill a run started elsewhere (by an agent's remote_exec, or through the API), use its run id:

1belt remote kill <run-id>...      # confirms first; --yes to skip

The run id is the exec_run_id in a remote_exec result, or the id of a run from the Exec Runs API. belt remote kill reports killed <id> once the remote confirms the run ended, and says so when it does not.

A kill, like a timeout, ends the whole process tree. Each run gets its own process group, and the daemon kills the group, so what sh -c "build && serve" started dies with the shell. This is why a run id is enough: there is no need for pkill -f, which matches on command text and also matches the shell that runs it. A process that left the group on purpose (setsid, a daemonizing server) survives; the run still ends, two seconds after the kill at the latest.

Disconnects. A short network drop marks the remote disconnected but does not kill commands already running on the host. Runs fail when the remote stays disconnected long enough to reach stopped (about 30 seconds) or when you signal them. Start the daemon again before that grace ends if you need long-running execs to survive a laptop sleep or Wi‑Fi outage.

REST API

For automation, use the exec and session APIs:

1. POST /remotes/{id}/execs creates a run
2. GET /execs/{id}/output?after_seq=N returns sequenced stdout/stderr chunks
3. GET /execs/{id} returns the run status
4. POST /execs/{id}/signal cancels a running exec
5. GET /remotes/{id}/sessions lists harness sessions on a connected remote with --agents (see List harness sessions)
6. POST /remotes/{id}/sessions opens a new harness chat in a folder (see Launch harness chat)

These calls need the remotes:read and remotes:write scopes; launching a harness chat also needs agents:execute. Full reference: Remotes API and Exec Runs API.

From agents

Agents can run commands on connected remotes when you enable the Remotes internal tool category (internal_tools.remote: true). The runtime exposes remote_list and remote_exec — the same exec-run domain as the REST API and belt remote exec, with the remote's --exec opt-in and API scopes still enforced. remote_list reports each remote's exec_enabled flag (whether the daemon started with --exec).

When inference drives a coding harness on your machine (a chat bound to a remote profile), the remote must be connected with --agents as well. Shell commands from the Remotes internal tools still require --exec only.

remote_exec completes asynchronously: the agent turn waits on the tool invocation until the exec run finishes (like an app tool waiting on its task). The run also appears as an execution node in the chat trace. Stopping the chat signals in-flight exec runs through the same graph sweep that cancels app tasks. If the remote disconnects before the command ends, the run becomes killed with error remote disconnected before the command finished so the turn does not hang.

→ Internal Tools: Remote tools

Troubleshooting

Next

→ CLI setup: command table and automation notes

→ Remotes API: register, list, update, and delete remotes

→ Exec Runs API: dispatch commands and read output