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.

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.

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.