Agents as an API (call your agents like an OpenAI model)
Switch on Agents as an API in Settings → Lab, publish the agents you want other programs to use, and make a key. Any tool on this computer that can talk to an OpenAI-compatible endpoint can then call your agent by name at http://127.0.0.1:19532/v1. It only ever runs on an API key you pay for by use — never your Claude or ChatGPT subscription — and nothing outside this computer can reach it unless you choose to share it on your own Tailscale network.
On this page
What it is
Many editors, scripts and chat front-ends already know how to talk to "an OpenAI model": they send a
list of messages to /v1/chat/completions and read the answer back. Agents as an API lets those same
tools talk to your Omniscio agents instead — with the project, personality, model and tools you set up
for them — without Omniscio handing out its own sign-ins or opening a door to the internet.
You decide everything: which agents are published, under which names, which keys may call which agents, how much each agent may spend in a day, and whether your own Tailscale devices may reach it.
Where to find it
- Switch it on: Settings → Lab → Agents as an API. It is off by default, and while it is off nothing listens on any port.
- The settings section: with the switch on, search Settings for "agents api", "openai" or
"published agents" to open the Agents as an API section. It has four parts:
- Status — whether the listener is answering, and on which address.
- Published agents — add, edit or remove an agent. Each one has a model name (the name callers
put in the
modelfield, lower-case letters, digits, dots, dashes and underscores), a project, an engine and optional model, an optional personality, a permission floor and a daily spend cap. - Keys — make a key, name it, tick the agents it may call, and revoke it at any time. The key is shown once, when you make it; copy it then. Removing a published agent takes it off every key and ends its conversations, so publishing a new agent later under the same name does not hand it to the old keys.
- Port and Tailscale — the port (19532 by default) and the Also answer on my Tailscale network switch.
- Desktop only. Keys and published agents can only be made or changed in the desktop app — not from the phone app, not by an agent, and not through the control server.
How it behaves
Calling it. Point your tool at base URL http://127.0.0.1:19532/v1 (or your chosen port), use
the key as the bearer token, and use a published agent's model name as model. GET /v1/models
lists the agents that key may call. POST /v1/chat/completions runs a turn, with or without
stream: true. Every other path answers "not found".
Conversations. Send the header X-Omniscio-Conversation: <any name> to keep a conversation going:
the same name continues the same agent session, across restarts too. Without the header, each request
starts a fresh session, and any earlier messages in the request are passed to the agent as one block of
background. A second request on a conversation while the first is still running is refused as busy
(409), and so is a retry while the session is still finishing a turn an earlier, timed-out request
interrupted — so a retry never receives the interrupted turn's reply as its own. Closing the connection
mid-answer stops the turn, and a caller that hangs up before its turn is sent starts nothing. A key can
never see or continue another key's conversations.
Where the agent works. An API session never works in your project's main folder. It gets its own isolated working copy, so a caller can never edit the files you have open. If its working copy has gone missing, or a restart would otherwise put it in your main folder, Omniscio first makes it a fresh working copy of its own; only when none can be made is the call refused, with the reason in the session — it never falls back to your main folder.
What it costs and who pays. A published agent runs only on a lane that is confirmed paid by use: a Claude setup that uses an API key only, a pinned API-key account with account switching locked, or another engine signed in with an API key. If no such lane is available, the call is refused with a plain error saying so — it never quietly falls back to a subscription you pay for monthly. The same check runs again before every continued conversation's turn and whenever the session restarts, judged on the engine, model, account and route the session itself is stored with — so a session that was moved onto another route, such as a company-funded one, is refused. A Claude API-key lane is also refused while Omniscio's usage cascade is set to move a session that runs out onto another provider, and an API session is never moved by the cascade or by the fallback that switches provider after an error. When an agent reaches its daily spend cap (five dollars a day unless you change it), further calls are refused until the next day.
What callers can and cannot do. Everything a caller sends reaches the agent marked as outside
input, not as your own instruction. API sessions run unattended at the agent's floor — read-only or
guarded, never higher — and any permission question the agent asks is answered "no" automatically.
While the Lab's native slash commands are on, a composer command that only you may run, such as
/rollback, is never run when a caller sends it: the session answers with a short note instead.
Who can reach it. Only programs on this computer. The listener refuses requests that come from a
web page in your browser, and refuses anything that arrives through Tailscale Funnel (the public
internet). To use it from your own other devices, switch on Also answer on my Tailscale network:
Omniscio then shows a tailscale serve command for you to copy and run yourself in a terminal.
Omniscio never runs it for you and never opens the port to your network on its own.
The limits of this version, worth knowing before you rely on it:
- Claude-family agents only. An agent published on Codex or another non-Claude engine is refused before any session starts.
- Answers arrive whole. With streaming on, the connection stays alive while the agent works and the answer is then sent in one go, not word by word.
- Usage shows zero. The token counts in each reply are always zero; check spend in Omniscio instead.
- Never a subscription, as above — you need an API key configured for the engine.
- API sessions are named "API · <agent>" in your session list and cannot be renamed.
- An API session keeps its engine and its route. Switching its engine, or the route that engine is reached by, from the session or the control server is refused; change the engine of the published agent in Settings, under Agents as an API, instead.
Errors look like OpenAI's. A refused call returns an OpenAI-style error body with a plain message
and a code such as invalid_api_key, model_not_permitted, conversation_busy,
daily_cap_reached, no_pay_per_use_lane or timeout (a turn that ran past ten minutes).
Related
- API keys — how the engines' own API keys are added, which is what a pay-per-use lane needs.
- Custom providers — the opposite direction: bringing an outside OpenAI-compatible provider into Omniscio.
- Agent permission level — what read-only and guarded mean for an agent.
- Personalities — the personality a published agent can carry.
- Chat gateway — talking to your agents from chat apps rather than from programs.
- CLI control — the separate control server for scripts that drive the app itself.
Last verified 2026-11-01