Integrations

Osaurus offers these integration surfaces:

• MCP server — connect any MCP client (Cursor, Claude Desktop, custom) to your Osaurus tools
• Remote inference providers — connect Osaurus to OpenAI, Anthropic, etc., so your scripts hit one endpoint
• Runtimes — run an agent on Claude Code, Pi, or another agent program instead of Osaurus's own loop (Runtimes)
• Osaurus Bundles — ship Osaurus with your own agents, skills, and MCP servers preinstalled (Osaurus Bundles)
• OpenAI/Anthropic/Ollama-compatible APIs — drop-in for any SDK, including Codex CLI
• Shared configuration — for native macOS apps to discover the local Osaurus instance
• The Osaurus iPhone app — pair your phone to chat with your Mac's agents from anywhere (Mobile)
• Messaging channels — reach your agents from Telegram, Slack, WhatsApp, n8n, and more (Agent Channels)

For LAN, Relay, and any non-loopback caller, authenticate with an osk-v1 access key — the snippets below show the pattern.

MCP Server

Osaurus is a full Model Context Protocol (MCP) server. Connect any MCP client to give AI agents access to your installed tools.

Cursor

Add to your Cursor MCP settings (Settings → Features → MCP Servers):

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

Or edit ~/.cursor/mcp.json directly.

Claude Desktop

Add to your Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

Other MCP Clients

Any MCP client that supports stdio transport can connect:

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

The osaurus mcp command:

• Proxies MCP protocol over stdio to the running server
• Auto-launches Osaurus if it isn't running
• Exposes all installed tools to the connected client
• Accepts --access-key (or OSAURUS_MCP_ACCESS_KEY) when the server has network exposure enabled — see CLI

HTTP MCP Endpoints

MCP is also available over HTTP:

Endpoint	Method	Description
/mcp/health	GET	Check MCP availability
/mcp/tools	GET	List active tools
/mcp/call	POST	Execute a tool

Example: List tools

curl http://127.0.0.1:1337/mcp/tools | jq

Example: Call a tool

curl -X POST http://127.0.0.1:1337/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_current_time", "arguments": {}}'

Remote Providers

Connect Osaurus to cloud AI providers to use remote models alongside your local ones through one API.

Adding a Provider

1. Open Settings… (⌘ ,)
2. Navigate to Providers
3. Click Add Provider
4. Choose a preset or configure a custom endpoint

Supported Presets

Provider	Description
Anthropic	Claude models with native API support
OpenAI	ChatGPT models
xAI	Grok models
OpenRouter	Access multiple providers (Anthropic, Google, etc.) through one API
Ollama	Connect to a local or remote Ollama instance
Custom	Any OpenAI-compatible endpoint

See Remote Providers for the full preset list, including OpenCode Zen / Go.

LM Studio isn't a provider preset — instead, Osaurus discovers models already downloaded by LM Studio and runs them directly with its own MLX engine.

Features

• Secure API Key Storage — Keys are stored in macOS Keychain, never in plain text
• Custom Headers — Add authentication headers for custom endpoints
• Auto-Connect on Launch — Automatically reconnect to providers when Osaurus starts
• Connection Health Monitoring — Real-time status indicators show provider availability

Configuration Options

When adding a custom provider:

Field	Description
Name	Display name for the provider
Base URL	API endpoint (e.g., https://api.openai.com/v1)
API Key	Authentication key (stored securely in Keychain)
Custom Headers	Additional headers for authentication
Auto-Connect	Connect automatically on launch

Using Remote Models

Once connected, remote models appear alongside local models in the chat model picker. Use them via the API:

# Use a remote OpenAI model
curl http://127.0.0.1:1337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Remote models are available to all connected MCP clients and work with tool calling.

OpenAI SDK Integration

Python

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:1337/v1",
    api_key="osaurus"  # Any value works
)

response = client.chat.completions.create(
    model="gemma-4-e2b-it-4bit",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

Streaming

stream = client.chat.completions.create(
    model="gemma-4-e2b-it-4bit",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

JavaScript/TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:1337/v1",
  apiKey: "osaurus",
});

const response = await client.chat.completions.create({
  model: "gemma-4-e2b-it-4bit",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

LangChain Integration

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

llm = ChatOpenAI(
    base_url="http://127.0.0.1:1337/v1",
    api_key="osaurus",
    model="gemma-4-e2b-it-4bit"
)

response = llm.invoke([HumanMessage(content="Hello!")])
print(response.content)

With Chains

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful translator."),
    ("human", "Translate to French: {text}")
])

chain = prompt | llm | StrOutputParser()
result = chain.invoke({"text": "Hello, world!"})

LlamaIndex Integration

from llama_index.llms.openai import OpenAI
from llama_index.core import Settings

Settings.llm = OpenAI(
    api_base="http://127.0.0.1:1337/v1",
    api_key="osaurus",
    model="gemma-4-e2b-it-4bit"
)

IDE Integrations

Codex CLI

OpenAI's Codex CLI can run against your local models. Settings… → Server → Overview has a Use with Codex CLI card: pick a model, then Copy the generated config or click Add to ~/.codex to write it.

Osaurus adds a [model_providers.osaurus] table to ~/.codex/config.toml (inside marked comments it maintains; the rest of the file is untouched) and writes an osaurus profile at ~/.codex/osaurus.config.toml holding model and model_provider. CODEX_HOME is honored when set. Start Codex with:

codex --profile osaurus

• Codex only speaks the Responses API (wire_api = "responses"), so requests land on POST /v1/responses.
• With network exposure off, Codex on the same Mac needs no key. With it on, the generated block adds env_key = "OSAURUS_API_KEY"; create an access key and export that variable in the shell running Codex.
• If config.toml already defines model_providers.osaurus by hand, the write is refused rather than duplicated; remove the manual table first.
• The profile's model_context_window is the context the server actually keeps: the model's context length, capped by KV Retention Override under Settings… → Server → Settings → Cache. Codex compacts the thread against it.
• Each Codex thread is its own conversation for the on-disk prompt cache (its prompt_cache_key becomes the session id), so resuming a thread reuses its cached prefix.
• To resume a non-interactive run, put the profile before the subcommand: codex exec --profile osaurus resume --last "…". Placed after resume, the flag is rejected, and without it Codex uses OpenAI instead of Osaurus.

Claude Code

Osaurus can also run agents on Claude Code. It's registered as a runtime under Settings… → Agents → Runtimes: click Sign In to use your own signed-in claude CLI, then pick Claude Code (Sonnet, Opus, or Haiku) in the chat's model picker. The agent's turns then run in Claude Code with its own tools, using your Claude subscription. Pi and Pi-based agent programs can be added the same way. See Runtimes.

Continue.dev (VS Code / JetBrains)

Add to ~/.continue/config.json:

{
  "models": [
    {
      "title": "Osaurus Local",
      "provider": "openai",
      "model": "gemma-4-e2b-it-4bit",
      "apiBase": "http://127.0.0.1:1337/v1",
      "apiKey": "osaurus"
    }
  ]
}

Cursor (as OpenAI Provider)

In Cursor settings, add a custom OpenAI-compatible model:

1. Open Settings → Models
2. Add OpenAI-compatible endpoint
3. Base URL: http://127.0.0.1:1337/v1
4. Model: gemma-4-e2b-it-4bit
5. API Key: osaurus

Native App Integration

Swift/macOS

Talk to a running Osaurus from any native app over the standard HTTP API:

import Foundation

let url = URL(string: "http://127.0.0.1:1337/v1/chat/completions")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
// For LAN/Relay, also set: Authorization: Bearer osk-v1.<your-access-key>

let body: [String: Any] = [
    "model": "gemma-4-e2b-it-4bit",
    "messages": [["role": "user", "content": "Hello!"]]
]
request.httpBody = try JSONSerialization.data(withJSONObject: body)

let (data, _) = try await URLSession.shared.data(for: request)

For non-loopback callers, mint an osk-v1 access key from Settings… → Server → Overview → Access Keys and pass it as a Bearer token. Local apps need one too for /agents, /sessions, /mcp/*, and /admin/config/* when Require Access Key for Local Admin Routes is on.

iPhone app

The Osaurus iPhone app pairs with your Mac from Settings… → Mobile → Generate Pairing Code and talks to your agents end-to-end encrypted, on the same network or (with Reach From Anywhere) through the relay. See Mobile.

Electron

// main/index.js
ipcMain.handle("osaurus:chat", async (event, message) => {
  const instance = { url: "http://127.0.0.1:1337" };

  const response = await fetch(`${instance.url}/v1/chat/completions`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "gemma-4-e2b-it-4bit",
      messages: [{ role: "user", content: message }],
    }),
  });

  return response.json();
});

Ollama-Compatible Clients

OllamaKit (Swift)

import OllamaKit

let client = OllamaKit(baseURL: URL(string: "http://127.0.0.1:1337")!)

let response = try await client.chat(
    model: "gemma-4-e2b-it-4bit",
    messages: [.user("Hello!")]
)

Python (Ollama Format)

import requests

response = requests.post(
    "http://127.0.0.1:1337/api/chat",
    json={
        "model": "gemma-4-e2b-it-4bit",
        "messages": [{"role": "user", "content": "Hello!"}],
        "stream": False
    }
)

print(response.json()["message"]["content"])

Web Applications

React

async function chat(message) {
  const response = await fetch("http://127.0.0.1:1337/v1/chat/completions", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "gemma-4-e2b-it-4bit",
      messages: [{ role: "user", content: message }],
    }),
  });

  const data = await response.json();
  return data.choices[0].message.content;
}

Next.js API Route

// app/api/chat/route.js
export async function POST(request) {
  const { message } = await request.json();

  const response = await fetch("http://127.0.0.1:1337/v1/chat/completions", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "gemma-4-e2b-it-4bit",
      messages: [{ role: "user", content: message }],
    }),
  });

  return Response.json(await response.json());
}

Authentication with Access Keys

Osaurus does not require authentication for local requests. If you expose your server to external clients — especially via Public Links — protect API endpoints with access keys.

Access keys use the osk-v1 format. Create a master key (any agent) under Settings… → Server → Overview → Access Keys, or an agent-scoped key from that agent's keys in Identity. Pass them as a Bearer token:

curl http://127.0.0.1:1337/v1/chat/completions \
  -H "Authorization: Bearer osk-v1.<payload>.<signature>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-4-e2b-it-4bit", "messages": [{"role":"user","content":"Hello!"}]}'

With the OpenAI SDK, pass the access key as the api_key:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:1337/v1",
    api_key="osk-v1.<payload>.<signature>"
)

Access keys can be scoped to a specific agent or to all agents (master). See Identity — Access Keys for details on creating, scoping, and revoking keys.

Integration Checklist

• Choose integration method — MCP, OpenAI SDK, or direct API
• Configure base URL — http://127.0.0.1:1337 (or custom port)
• Set model name — Use lowercase with hyphens
• Set up authentication — Create an access key if exposing endpoints externally
• Handle streaming — Enable for better UX
• Install tools — If using MCP, install needed plugins
• Test error handling — Handle connection and model errors

Troubleshooting

Connection Refused

• Verify Osaurus is running: osaurus status
• Check port matches configuration
• Ensure firewall allows localhost connections

MCP Tools Not Appearing

• Verify tools are installed: osaurus tools list
• Restart your MCP client after installing tools
• Check osaurus mcp runs without errors

Model Not Found

• List available models: curl http://127.0.0.1:1337/v1/models
• Use exact model name from list
• Download model if needed from Settings… → Local Models

CORS Errors (Browser)

• CORS is enabled by default for all origins
• Verify request includes correct headers
• Check browser console for specific error

---

Related:

• HTTP API — endpoint reference
• SDK Examples — runnable snippets
• Remote Providers — connecting Osaurus to OpenAI/Anthropic/etc.
• Remote MCP Providers — connecting Osaurus to remote MCP servers
• Identity — access keys and pairing