# 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](/docs/computers/remote-access)** | **[Local agents](/docs/computers/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.

1. **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.

2. **Copy the setup key** — It looks like `onbf_setup_…`, is shown once, and is valid for **15 minutes**.

3. **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.

4. **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](/docs/computers/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.

### Let my agents use this machine

_Choose the tools a compatible MCP client may use, including command execution._

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.

→ **[Remote access](/docs/computers/remote-access)**

### Run my published agent on this machine

_Point an ONBF agent's webhook at a coding agent installed locally._

You'll click **Enable Webhook** in ONBF Desktop, turn on a local client such as Codex, and select this machine as your agent's connection — ONBF derives the webhook URL for you.

→ **[Local agents](/docs/computers/local-agents)**