Bring your own machine

Background runs normally happen on our servers. If you'd rather an agent run on a computer you own - to work on real files in a real folder, use hardware you already have, or just avoid cloud CPU charges - you can register that computer as a "your machine" and pick it as where a scheduled agent runs.

Set it up

1. In Settings, create a gateway API key if you don't have one yet.

2. On the computer you want to use, run:

   npx @kumin-consulting/nextos-runner --key <your gateway key> --dir ~/agent-workspace

   Replace ~/agent-workspace with whichever folder you want the agent's file tools to work in.

3. Leave that command running. Within a few seconds, the machine appears in Settings > Agents > Your machines.

4. Open any scheduled agent, and under Schedule, set Run on to the machine you just registered - this also applies the next time you run that agent right now, not only on its own schedule.

What it can do

While a job is running on your machine, it can:

• Read, write, and edit files inside the folder you chose when you started it.
• Run shell commands - but only ones you explicitly allow with the companion's --allow option. Nothing runs on your machine that isn't on that list.
• Fetch web pages, through the same network policy your account already has.
• Ask you a question mid-run and wait for your answer, exactly like a run in the tab.

It can't see or touch anything outside the folder you chose, and needs your account's Background runs setting turned on first (same requirement as any other background run).

Cost and billing

A run on your own machine uses your computer's CPU, not ours - it doesn't count against any cloud sandbox hours your plan includes. It still uses your account's own AI provider key, the same as any other background run.

Removing a machine

In Settings > Agents > Your machines, remove any machine you no longer want to use. It stops being able to pick up new work immediately; anything already running on it finishes or fails on its own.

Run Claude Code or Codex on your machine

If you already pay for Claude Pro/Max or ChatGPT and have Claude Code or Codex installed and signed in, you can run your NextOS agents through that subscription instead of any API key - on a computer you register the same way as above.

The one line

1. In Settings, create a gateway API key if you don't have one yet (or use Settings > Developer > Connect Claude Code or Codex, pick "Your machine", and it mints one for you).

2. On the computer where Claude Code or Codex is installed and signed in, run:

   curl -fsSL https://www.jonkum.in/connect.sh | bash -s -- bridge <your gateway key>

   It checks that Node 18+ and at least one of the two CLIs are on your PATH, then starts the same companion the plain "bring your own machine" setup above uses, working in ~/nextos-workspace by default.

3. Leave it running. The machine shows up in Settings > Agents > Your machines with a badge for each CLI it found.

4. Under Settings > Privacy > Background runs, choose "Claude Code (your subscription, on your machine)" or "Codex (your subscription, on your machine)" as where background work runs.

What the agent can do there

Once a job lands on that machine, the CLI you're signed into runs headlessly with its own built-in tools working inside the folder you chose, plus a NextOS connection so it can also read and write your account's files over MCP. The model bill goes to your Claude Pro/Max or ChatGPT subscription, exactly as if you'd typed the prompt yourself in a terminal - NextOS is never charged for these calls and never sees a price for them.

We never store or reuse that subscription's sign-in: the CLI is already logged in on your machine before the bridge starts it, and nothing about that login is sent anywhere.

Stopping it

Close the terminal running the bridge, or press Ctrl-C. The machine stops claiming new work immediately; anything already running finishes or fails on its own, same as removing any other machine.

What's next

• Turn on background runs if you haven't already - it's required before any machine, cloud or your own, can run a schedule.
• See how agents and automations fit together.