+BETA QUICKSTART

From curious
to connected.

Start with a safe synthetic run. When you’re ready, bring your own model and point a compatible tool at Cairn.

Before you start

Node.js24.12.0 or newerDownloadCairn Local ZIPFirst runNo model or API key needed

Download Cairn Local on GitHub

STEP 01

Take the synthetic route.

Open a terminal in the extracted Cairn folder and run the demo.

Terminal

npm run demo

Core routing and the demo use Node built-ins. No dependency install is needed for this path.

What to expectTemporary sample providers demonstrate JSON and streaming responses, then shut down. No model is loaded and no external inference call is made.

STEP 02

Bring a local model.

Start an existing Ollama service with a model already installed. Copy the example configuration, then set upstreamModel to that model’s installed ID.

Local router setup

Copy-Item config.example.json config.local.json
# Edit upstreamModel in config.local.json before continuing.
$env:ROUTER_API_KEY = node -p "require('node:crypto').randomBytes(32).toString('hex')"
node src/cli.js check config.local.json
node src/cli.js start config.local.json

Keep the router key in your local process. The website never needs your key or provider credentials.

YOUR WORKSPACE

Start the router and dashboard together.

After configuring your installed model, stop any separately running Cairn router. Set a separate operator key in the same terminal, then start the combined app.

PowerShell · local workspace

$env:CAIRNMESH_OPERATOR_KEY = node -p "require('node:crypto').randomBytes(32).toString('hex')"
Set-Clipboard -Value $env:CAIRNMESH_OPERATOR_KEY
npm run app -- config.local.json

Open 127.0.0.1:8788/app/ and paste the operator key to unlock. Clear your clipboard afterward. Keep keys on your own device; never paste them into the hosted website or chat.

macOS/Linux: set CAIRNMESH_OPERATOR_KEY with a fresh random value in the environment, transfer it through your normal secure local workflow, then use the same npm run app command.

Workspace setup and troubleshooting

STEP 03

Give your tools one endpoint.

Use these values in a tool that supports OpenAI-compatible Chat Completions. Cairn supports regular JSON responses and streaming.

Base URL: http://127.0.0.1:8787/v1
Model alias: local-chatFrom the example configuration
API key: Your router bearer keyUse the value generated in step 02

The router key authenticates your tool to Cairn. Your upstream provider keys stay in the router process environment; configuration stores only their environment variable names.

Choose your next route.

Connect a remote API

Add an OpenAI-compatible HTTPS provider to your configuration. Map the client-facing model alias to its upstream model ID, configure pricing, and validate the file before starting the router.

Choose substitutes intentionally. Different models behind the same alias may respond differently.

Provider configuration guide

Connect a trusted peer

Configure the peer endpoint and pin its expected signed identity. The operator explicitly chooses the models it offers and the identities it accepts.

Read the operator overview

Understand Local only

Local only restricts eligible endpoints to loopback addresses. If none is available, the router returns a 503 error instead of selecting a remote route.

This checks endpoint placement. A local service could itself forward data elsewhere, so you still need to trust the software you run.

Read the security boundaries