olace

[ daemon & cli ]

For AI agents

This page is written for a coding agent (Claude Code, Codex CLI, Cursor, Gemini CLI, or any other) that a person has asked to set up Olace, use their local model from their phone, or give a tool a private OpenAI-compatible or Anthropic-compatible endpoint. Every command here runs with no terminal on stdin. Two moments need the person: the 6-digit sign-in code from their email, and the pairing code on their other device. Relay both.

The same flow ships as installable skills: npx skills add Olace-app/skills (source). Every docs page is available as raw markdown at https://www.olace.app/docs-md/<page>.md, and the index for agents is /docs/llms.txt. Use the www. host when fetching: olace.app redirects to it, and a client that does not follow redirects reads the redirect body as the page.

What you are setting up

Olace turns one computer into a private AI host. The daemon runs in the background, the olace command drives it, and every device the person pairs streams from the host's models over an end-to-end encrypted connection, directly on the LAN or through Olace's relay when away. Nothing needs opening in a firewall or router, no VPN, no public address: away from home the host reaches the relay with outbound connections only, and if a firewall blocks the direct LAN connection, devices use the relay instead. Olace's servers never see the prompts or responses of local and paired inference, and local and paired AI is free on every plan.

Prerequisites: a Linux, macOS, or Windows computer (headless is fine), and a local AI runtime. Olace uses Ollama, LM Studio (or its headless llmster), or llama.cpp, whichever is installed. It can install one, but that step needs a terminal, so if none is present install one yourself first and continue.

1. Install

# Linux and macOS
OLACE_NONINTERACTIVE=1 sh -c "$(curl -fsSL https://olace.app/install.sh)"
export PATH="$HOME/.olace/bin:$PATH"
olace version

# Windows
$env:OLACE_NONINTERACTIVE = "1"
irm https://olace.app/install.ps1 | iex
& "$env:USERPROFILE\.olace\bin\olace.cmd" version

OLACE_NONINTERACTIVE=1 skips the installer's questions (the handoff into setup, and on Linux and macOS a PATH edit) so it never blocks. The daemon, the olace command and the background service are installed either way. On Linux and macOS, ask the person whether they want ~/.olace/bin on their PATH permanently; the installer prints the line for their shell. The Windows installer adds it to the user PATH itself. Re-running the installer updates an existing install in place.

2. Set up local AI

olace setup < /dev/null

Four steps, each skipped when already done: a runtime, a starter model sized to the detected hardware, the Python sandbox (so models can run code on this machine), and sign-in. Without a terminal it prints what each step would do instead of asking.

  • Exit 0 with "Setup complete": continue.
  • Exit 2 with "Some steps need a terminal to confirm": the output names the step. A runtime install is the usual one; install the runtime yourself and re-run.
  • A specific model rather than the starter pick: olace pull qwen3.5:4b. With one runtime installed, it takes every pull; otherwise Ollama tags use :, LM Studio ids use /, a Hugging Face user/repo-GGUF:QUANT tag goes to llama.cpp, and --provider ollama|lms|llamacpp overrides. Pulling never prompts.

3. Sign in

Sign-in requests a 6-digit code by email and then reads it from stdin. The code does not exist when the command starts, so keep stdin open and append the code once the person gives it to you:

: > /tmp/olace-code.txt
(tail -f /tmp/olace-code.txt | olace signin --email USER@EXAMPLE.COM > /tmp/olace-signin.log 2>&1 &)
sleep 5 && cat /tmp/olace-signin.log

A 6-digit code was sent to USER@EXAMPLE.COM. It expires in 10 minutes.
Enter the code (or 'r' to resend, blank to cancel):

Ask for the code, then:

echo 575537 >> /tmp/olace-code.txt
sleep 10 && cat /tmp/olace-signin.log
pkill -f "tail -f /tmp/olace-code.txt"

Signed in as USER@EXAMPLE.COM.
The Olace background service is running.

A wrong code prints "That code is not correct or has expired" and waits again. If the log says "Start the background service later", run olace service install. The daemon picks up the new session on its own. On Windows, run olace signin --email ... in a terminal the person can type into. Verify with olace whoami --json.

4. Pair the person's other devices

The host shows a code; the person enters it on the device that should use this computer's models. The command waits until the code is claimed, so run it in the background:

(olace pair --code --ascii > /tmp/olace-pair.log 2>&1 &)
sleep 3 && head -1 /tmp/olace-pair.log

The first line is Pairing code: ABCD-1234. Tell the person:

  • On a phone: open Olace, sign in with the same account, go to Settings › Remote Access › Pair a computer, enter the code (or scan the QR in the log).
  • On another computer with Olace: olace pair claim ABCD-1234.

It exits 0 and prints Paired with <device name>. when claimed. An expired code is replaced with a fresh one in the same log. Verify with olace pair list --json (this computer's pairings are in pairs) or olace status --json (pairs.active). The free plan includes one pairing; pairing_usage in the pair list shows used, cap, and the plan that raises it. Report a full cap rather than retrying.

5. Serve local apps

olace bridge on --require-key
olace bridge status --json

This turns on the Olace Bridge, a local endpoint for every local and paired model, loopback only, serving OpenAI Chat Completions and Responses at http://127.0.0.1:5578/v1 and Anthropic Messages at http://127.0.0.1:5578 (base URL without /v1 for Anthropic SDKs and Claude Code). When no key is set yet, --require-key mints a Bearer key and prints it once, on the line after "Bridge API key (shown once, stored in daemon.json):". Capture it there; olace bridge key afterwards only says whether one is set, and olace bridge key --regenerate replaces a key you no longer have. Point the person's tool at the base URL with that key and a model id from GET /v1/models (ollama/qwen3.5:4b runs here, home-pc/ollama/qwen3.6:27b runs on the paired host called "Home PC"). The key is accepted as Authorization: Bearer <key> or x-api-key: <key>. The Bridge serves chat completions, the Responses API (Codex CLI: OPENAI_BASE_URL=http://127.0.0.1:5578/v1, or a config.toml provider with wire_api = "responses"), the Anthropic Messages API (Claude Code: ANTHROPIC_BASE_URL=http://127.0.0.1:5578 ANTHROPIC_API_KEY=<key> ANTHROPIC_MODEL=<model id> claude), completions and embeddings.

Verify

olace status --json

Read account.signed_in, daemon.running, daemon.tunnel_connected (reachable from the person's other devices), runtimes.<name>.alive, python.ready (with python.hint saying why when python.sandbox_supported is false), pairs.active, bridge.listening. On Linux, service.survives_logout: false means the daemon stops when the person logs out; sudo loginctl enable-linger <user> fixes it and needs their admin rights, so tell them rather than work around it. olace list shows the models this computer can serve, and olace chat "say hi in five words" exercises one.

Exit codes

0 success, 1 failure, 2 usage error or a step that needs a terminal, 3 not signed in, 4 network error, 5 daemon not running, 6 update required (olace update).

Do not

  • Do not run olace signout unless asked. It signs out the whole computer, including the desktop app, and clears pairing and file sharing (local models and the Bridge keep their settings). Without a terminal it needs --yes.
  • Do not edit ~/.olace/daemon.json by hand. The daemon and the app own it.
  • Do not paste the sign-in code, pairing code, or Bridge key anywhere except the command that consumes it.
  • Do not open ports or set up a VPN for Olace. The host is reachable through outbound connections only.