# Neoo One integration

> How Neoo One runs its agents on Neoo Connect, with the Neoo Forge provider and Connect's local API.

Neoo One (the Neoo desktop app for organisations) can run its agents on **Neoo Connect** installed on the same computer. Two Connect features make this work.

## Neoo Forge provider

Conversations with the `neoo-forge` provider work like this:

- the agent loop and the model (Codex, with the Neoo platform's accounts) run on **Neoo Forge**, never on your computer, and no ChatGPT token is stored locally;
- every tool — reading and editing files, searching, running commands — runs **on your computer**, with the usual approvals (Default, Auto, Full Access, Plan). In Auto, file edits in the workspace run without asking, while commands and deletions are still submitted to you;
- the model's history stays on your computer, in Connect's state folder (`neoo-forge-sessions/`), so a conversation resumes where it stopped.

Connect gets a short-lived access (15 minutes, renewed automatically during long turns) from Neoo for each turn. Only a Connect that Neoo One linked to its user receives one; any other Connect gets `connect_not_enrolled`.

> [!NOTE]
> The provider isn't offered in the Neoo IDE model picker yet: Neoo One selects it for its own conversations.

## Tools from the app

An app that drives Connect can give its own tools to `neoo-forge` conversations. It declares them in `client-mcp.json`, in Connect's state folder, and Connect reads that file at the start of each turn:

```json
{
  "servers": {
    "neoo": { "command": "C:/…/Neoo One.exe", "args": ["--neoo-tools"], "selfConfirmed": true }
  },
  "hideHostTools": ["browser", "mobile"]
}
```

- Each server is a local MCP server (stdio), at most 4. Its tools are offered next to Connect's own tools. If a name is already used by a Connect tool, Connect's tool is kept.
- `selfConfirmed`: the server asks you to confirm its own changes, so Connect doesn't ask a second time. Without it, its tools follow the usual approvals.
- In Plan mode, only read-only tools from these servers are offered.
- `hideHostTools`: Connect tools the app doesn't want to offer, for example because they duplicate its own.
- Each server receives `VATO_CONNECT_AGENT_ID`, the Connect conversation that calls it, so the app can match it with its own conversation.

Neoo One declares its Neoo tools this way: tickets, tasks, clients, mail, calendar, time, Notes, and its screens and browser. They run in Neoo One with your Neoo session and rights, and Neoo One asks you to confirm each change. Neoo One must be open and unlocked for these tools to work.

## Bots on a local Connect

Bots normally live on Neoo Cloud. An app that starts its own Connect (Neoo One) can also host bots on your computer: it starts Connect with `VATO_CONNECT_LOCAL_BOTS=1`.

- Bots work like on Neoo Cloud: memory, brief, journal, routines, background works, delegated tasks and child bots. Their routines run while this computer is on and Connect is running.
- A bot can use the `neoo-forge` provider, like the app's other conversations.
- Not available to these bots: Computer Use, Composio integrations, the Neoo Cloud vault and thread goals. Bots tell you so instead of improvising.
- The app manages the bots through the local API: `onRemoteBotsRequest`, `onBotAction`, `onBotRpc`, `onBotCloudImport` and `onBotCloudExport`. These are the same actions as Neoo mobile, and Connect only accepts them when it hosts local bots (`bots: true` in `GET /v1/health`).

## Local API

While `vato-connect` runs, it also listens on `127.0.0.1` (never on the network) so that an app on the same computer can drive it without going through the cloud:

| Request | What it does |
| --- | --- |
| `GET /v1/health` | Version and whether Connect is signed in. |
| `POST /v1/call` | `{ "handler": "onCreateAgent" \| "onPrompt" \| "onApprovalRespond" \| "onStopAgent" \| "onMessagesRequest" \| …, "args": { … } }` — the same actions as Neoo mobile. |
| `GET /v1/events` | Server-sent events: everything Connect publishes (conversations, messages, statuses, replies). |

Access needs the token written in `local-api.json` in Connect's state folder (`~/.vato-connect` by default; readable only by your user). Requests sent by a web page (an `Origin` header, or an unexpected host) are refused. Set `VATO_CONNECT_LOCAL_API=0` to turn the local API off.

Source: https://vatoide.com/docs/connect/neoo-one-integration