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 use any placeholder API key (the endpoint ignores it - being on your machine is the credential).

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:   local                    (any non-empty value)

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: "local"
  api_mode: chat_completions

Hermes 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: "local",
        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.

Request headers

Optional headers refine a call:

Header	Effect
X-Your-Own-AI-Conversation: <id>	Groups turns into one conversation in your records (otherwise grouped per client)
X-Your-Own-AI-Memory: off	Skip memory injection for this call
X-Your-Own-AI-Record: off	Don't record this exchange in your records
X-Your-Own-AI-Lean: fastest|strongest	On-device model preference override for this call

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

• One conversation id per logical thread keeps your records tidy.
• 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

1. 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).
2. 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/health

Returns 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.