Connecting apps and agents
Connecting an app is configuration, not a plugin: set the base URL to http://localhost:11435/v1, set the model to one of your AIs, and leave the API key empty, or use any placeholder if the tool insists on one (apps on this computer need no key - being on your machine is the credential). Use any placeholder except local: the app keeps that value for its own Build sessions, and an agent call that carries it is left out of your records.
Typical configurations
Most tools ask for the same three values:
Base URL: http://localhost:11435/v1
Model: <your AI's model name> (Copy setup in the app gives it exactly)
API key: yourownai (any value except local, if asked)This works for OpenAI-compatible agent frameworks (Hermes Agent, OpenClaw, and similar), coding editors with custom-endpoint support, and your own scripts through any OpenAI client library.
Hermes Agent
In the setup wizard (first run, or hermes model anytime), choose Custom endpoint (self-hosted / vLLM / etc.) and answer its three questions with the values from Copy setup. Or edit ~/.hermes/config.yaml directly - note the model name goes under default::
model:
provider: custom
default: "your-ai's-model-name"
base_url: "http://localhost:11435/v1"
api_key: "yourownai"
api_mode: chat_completionsHermes appends /chat/completions itself, so the base URL ends at /v1. From another device, use the network endpoint and access key from Settings → External access instead (the key can also live in ~/.hermes/.env as OPENAI_API_KEY).
The OpenRouter trap
If ~/.hermes/.env contains an OPENROUTER_API_KEY, Hermes may route to OpenRouter even with a custom provider configured (a known Hermes issue). Remove that line, and delete any fallback_providers: entries pointing at other providers - otherwise errors silently "fail over" away from your machine.
OpenClaw
OpenClaw's setup has two required steps: define the provider, and allowlist the model in provider/model-id form - without the second step it rejects the model. In your OpenClaw config (openclaw.json):
{
models: {
providers: {
yourownai: {
baseUrl: "http://localhost:11435/v1",
apiKey: "yourownai",
api: "openai-completions",
models: [
{
id: "your-ai's-model-name",
name: "Your AI",
contextWindow: 32000,
maxTokens: 8192,
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
}
]
}
}
},
agents: {
defaults: {
model: { primary: "yourownai/your-ai's-model-name" }
}
}
}Set contextWindow to your AI's model context (shown on the Offline Models page). From another device, swap baseUrl for the network endpoint and apiKey for the access key.
Agents
Point agents at the <ai-name>:agent variant - same AI, tuned for tool use, without persona flourish in the output.
In agent mode your system prompt leads. From version 0.9.1 two ground rules are always sent ahead of it, whatever it says: never help anyone harm themselves or others (and point a person who may be at risk to real help), and do not invent facts or results. They carry no voice or style, so your agent's own character is untouched. Persona mode has always carried the AI's full ground rules.
Request headers
Optional headers refine a call:
| Header | Effect |
|---|---|
X-Your-Own-AI-Conversation: <id> | Groups turns into one conversation in your records. Without it (or the standard user field in the request body), each call is recorded as a conversation of its own |
X-Your-Own-AI-Mode: agent | Agent mode, the same as the <ai-name>:agent model: your system prompt leads, and the AI lends its model, memory and records, not its persona |
X-Your-Own-AI-Memory: off | Leave out what the AI remembers about you for this call. The AI keeps its personality. Works in agent mode; in persona mode from version 0.9.1 (earlier versions always include memory there) |
X-Your-Own-AI-Record: off | Don't record this exchange in your records |
For an AI set to Auto, four more steer the pick for one call. Without them, your choices in Routing settings apply; an AI set to a specific model ignores them.
| Header | Values | Effect |
|---|---|---|
X-Your-Own-AI-Task | code, math, reasoning | The kind of question (anything else counts as general) |
X-Your-Own-AI-Difficulty | easy, hard | How hard the question is |
X-Your-Own-AI-Lean | speed, balanced, quality | Prefer fastest, Balanced or Prefer strongest among the models on this computer |
X-Your-Own-AI-Online-Share | frontier, balanced, local | Online-first, Balanced or Local-first, for an AI set to Auto - Online and Offline |
Conversations from external apps appear on the Memory page with an "API" badge and the calling app's name where it identifies itself (standard User-Agent / X-Title).
Good citizens checklist
- Send one conversation id per logical thread: without one, every call becomes a conversation of its own in your records.
- Long agent sessions: the endpoint streams; keep connections open rather than polling.
- The endpoint is loopback-only by default. To reach it from another machine, enable network access in Settings → External access and use the access key it mints - see below.
From another device on your network
- On the Your Own AI machine: Settings → External access → Other devices on this network → toggle on. Copy the network address and the access key it shows (your firewall may ask to allow the app the first time).
- On the other device, configure your app with:
Base URL: http://<that-machine's-address>:11435/v1
Model: <your AI's model name>
API key: <the access key>The key rides the standard Authorization: Bearer header, so any OpenAI-compatible client's API key field works as-is. Requests without the key are refused with invalid_access_key. Enable only on networks you trust - anyone on the network with the key can chat with your AIs.
Health check
curl http://localhost:11435/healthReturns ok while the app is open. If a connection fails, the app being closed is the first thing to check - the endpoint lives only while Your Own AI runs.