Remote Tasks

Remote tasks (optional)

Remote tasks let you send Claude Code or Codex tasks to this Mac from anywhere, for example from Slack through OpenTag. A small worker on the Mac picks up a task and runs it on the account you choose, in a folder you approved. Each task works in its own git worktree, so your own checkout is never touched.

Remote tasks are off by default. Nothing runs until you pair the Mac, start the worker, pick an account and folders, and pass the live check.

Connect this Mac

From the menu bar: Settings → Remote → Connect to OpenTag…. From a terminal:

openswap worker connect

Your browser opens on OpenTag. Approve the Mac there, and the browser hands the pairing back to the Mac. The browser tab then shows whether it worked and what to do next. The Mac says which workspace it paired with. To use a server other than OpenTag, choose Use another server… or run openswap worker connect <url>.

The approval has to happen in a browser on the same Mac. Over SSH, or with a server that has no Connect page, pair with the command OpenTag shows instead:

openswap worker pair <url> <code>

When the Mac’s key has expired (or is about to), the same button reads Reconnect and keeps the Mac’s worker ID.

Guided setup

Right after pairing, OpenSwap walks you through four steps. Run them again any time with Settings → Remote → Set up Remote tasks… or openswap worker setup.

1. Start the worker. It runs in the background and stays on after a restart. Until it runs, the Mac shows Offline. Same as openswap worker enable, or Settings → Remote → Enable local worker.
2. Pick the account. Tasks run on the Claude or Codex account you pick (openswap worker account claude:4). Your default login is untouched.
3. Pick the folders. Folders where remote sessions can work. A git repo is one folder; a folder of repos (such as ~/GitHub) offers each repo inside it. Each task gets its own worktree on an openswap/ branch.
4. Summary. A checklist of what is done and the next command to run.

In the menu bar these steps are dialogs that match the setup window, with an account picker and Close Setup to stop part-way.

Go live

Jobs do not really run until this Mac passes a live check and you turn live tasks on:

openswap worker live-check                     # Codex account
openswap worker claude pin                     # Claude account: pin Claude Code first
openswap worker claude prepare
openswap worker live-check --provider claude
openswap worker live status

The live check runs a few short real tasks here and offers to turn live tasks on when they pass. The worker protocol doc has the details.

What a task may do

Each remote session follows that account’s own Claude or Codex permission settings, and anything that would ask for permission is denied. You can limit every task on this Mac further; these are set only on the Mac, never from the service:

openswap worker permissions read-only     # or: follow, no-shell
openswap worker origins                   # where tasks may come from
openswap worker origins refuse assistant  # refuse one source

To let tasks read a folder without changing it, add it with openswap worker workspace add --read <folder>; results go to ~/OpenSwap Research/<id>. The service only ever sees folder IDs and labels, not paths.

Day to day

openswap worker status        # the worker, the service link and the running task
openswap worker stop          # stop the running task
openswap worker pause         # stop taking new tasks (--off takes them again)
openswap worker disable       # stop the worker and turn Remote tasks off
openswap worker worktrees     # list the tasks' worktrees, or prune finished ones
openswap worker unpair        # forget the pairing

Uninstalling OpenSwap also removes the worker. Every worker command: openswap worker --help.