DocumentationComputers
Computers — ONBF Desktop
ONBF Desktop registers one of your machines with your ONBF account, so agents can act on it. Install it once, then use it to give agents remote control of that machine, to run local coding agents, or both.
#What it is
ONBF Desktop is a small app you install on a Mac you own. It has no sign-in screen: you register the machine once with a short-lived setup key generated on ONBF.ai, and the app then keeps its own long-lived device credential on the machine. Raw long-lived credentials stay in the Mac's Keychain — ONBF stores only hashes and public identifiers.
The app provides three distinct services, and it helps to keep them apart:
- Local MCP — available directly on the Mac and starts on its own. It needs no ONBF service enabled and is not affected by anything you switch on or off for ONBF.
- Remote access (Remote MCP) — the ONBF-managed remote MCP service, so an MCP client elsewhere can reach this machine.
- Local agents (Webhook) — lets ONBF agents dispatch runs to the local clients you enable, such as Codex.
Remote access (Remote MCP) and Local agents (Webhook) are the two ONBF-facing services. They're independent — enabled separately, revoked separately, and either one works fine on its own:
| Remote access (Remote MCP) | Local agents (Webhook) | |
|---|---|---|
| What it does | Lets an agent see and control this machine | Lets ONBF start a coding agent installed on this machine |
| Who it's for | Anyone using AI agents | Builders publishing an agent on ONBF |
| Where work starts | In your MCP client, which asks this machine to do something | In an ONBF agent run, which is dispatched to this machine |
| Needs an ONBF agent? | No — any compatible MCP client works. Traffic still travels through ONBF's managed relay. | Yes — it's your agent's webhook target |
| Read next | Remote access | Local agents |
Nothing to open on your network: ONBF Desktop initiates outbound connections to ONBF. It does not expose an inbound public control port, so there is no port to forward, no tunnel to run and no firewall rule to add.
Remote access works outside ONBF: You don't need to build or publish anything to use it. Register a machine, grant the tools you're comfortable with, and connect any compatible MCP client that supports the remote endpoint and bearer authentication — Claude Desktop and Cursor, for example. Your machine becomes a tool that agent can use, with traffic flowing through ONBF's managed relay.
#Install the app
Sign in on ONBF.ai, open the Computers page, and download ONBF Desktop from there. The app itself has no account to sign in to — the machine is linked to your account during registration.
macOS (Apple Silicon) today: The current build targets Apple Silicon (ARM64) Macs on macOS 14 or later — it will not launch on an Intel Mac. Windows and a headless CLI build for servers and CI runners are listed in the download panel and are not available yet.
#Register the machine
Registration is a one-time handshake that links the installed app to your account. You generate a short-lived setup key in the browser and paste it into the app; the Mac creates its own long-lived device credential locally and submits the registration using that key.
Sign in on ONBF.ai and open the Computers page
Builders: Dashboard → Computers. Users: Computers in your account menu. Both generate the same kind of key.
Copy the setup key
It looks like
onbf_setup_…, is shown once, and is valid for 15 minutes.In ONBF Desktop, open Settings → Advanced → ONBF Computer
Paste the key there and click Register This Mac. The Mac creates its long-lived device credential locally and submits the registration with the setup key — ONBF keeps only hashes and public identifiers, never a reusable raw long-lived credential. The machine then appears in your Computers list with the name and platform it reported.
Switch on the ONBF service you want
Registration enables neither ONBF-facing service. Click Enable Remote MCP, Enable Webhook, or both, in ONBF Desktop. Local MCP is unaffected either way — it's already running on the Mac.
The key is shown once and expires quickly: The plaintext setup key is displayed a single time and only ONBF's hash is kept, so it can't be shown again. It also expires after 15 minutes. An expired or already-used key looks a lot like a broken app — if the desktop app rejects it, generate a new one rather than retrying the old value.
#Reading the status
A computer's row shows two different things: whether the machine is reachable, and what each service on it is doing. Confusing the two is the most common source of "why isn't this working".
Machine presence comes from the app checking in. The app synchronizes regularly; ONBF considers the machine Online when it has heard from it within the last 2 minutes.
| Presence | Means | Fix |
|---|---|---|
| Online | ONBF has heard from the machine within the last 2 minutes. | — |
| Not connected | Nothing recent from the machine — it's asleep, offline, or the app isn't running. | Wake the machine and make sure ONBF Desktop is open. |
| Revoked | The whole computer was revoked, so its ONBF registration is no longer valid. | Register it again with a new setup key. |
Each ONBF-facing service then has its own state, which is why an online machine can still refuse work:
| Service state | Means | Fix |
|---|---|---|
| Not enabled | This machine never switched the service on. Normal — not an error, and not the same as revoked. | Enable it in ONBF Desktop (Enable Remote MCP or Enable Webhook). |
| Active | Enabled and authorized. That's a permission state, not a promise that work can be routed right now — it still needs the machine to be Online and a relay to be available. | — |
| Revoked | The service was switched off on this machine (Disable Remote MCP or Disconnect Webhook). The other service is unaffected. | Enable it again in ONBF Desktop. |
"Not connected" is not "Revoked": Not connected is about the machine, and it clears itself when the machine wakes up. Revoked is about lifecycle: something was deliberately switched off or revoked. If a service says Active but the machine says Not connected, nothing is misconfigured — the machine is just asleep.
#Revoking access
You can switch off one service and keep the other, or revoke the whole computer. Turning a single service off is the right move when you want to stop one kind of access without reinstalling anything.
- Switch off one service — do this in ONBF Desktop with Disable Remote MCP or Disconnect Webhook. The service stops locally straight away; server-side revocation and credential propagation may take up to a minute. The machine stays registered and the other service keeps working.
- Revoke the whole computer — start this from the Computers page on ONBF.ai or from Settings → Advanced → ONBF Computer in the app. It invalidates the ONBF computer registration and its ONBF-facing services, and the app has to register again with a new setup key.
Getting back to working depends on which one you did:
- Revoked a service → re-enable it in ONBF Desktop (Enable Remote MCP or Enable Webhook).
- Revoked the computer → register again with a new setup key.
Local MCP is separate: Revoking the computer ends its ONBF registration and its ONBF-facing services. The direct Local MCP service on the Mac keeps running and keeps its own separate local token — that isn't part of the ONBF registration.
Turning off Local agents breaks live agents: If any published agent uses this machine as its webhook target, disconnecting the Webhook service stops those agents from receiving runs. The computer's detail panel lists every agent bound to it, so check there first — see Local agents.
#Pick your path
The machine is registered. What you do with it depends on which of the two ONBF-facing services you're here for.
What do you want this computer to do?
Both can be true — the services are independent, so you can come back and read the other one.
You'll click Enable Remote MCP in ONBF Desktop, choose exactly which tools an agent may use, and connect your MCP client. No ONBF agent required. Screen control also needs the macOS permissions granted on that machine.