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 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. The host only makes outbound connections: nothing to open in a firewall or router, no VPN, no public address. 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 two questions (a PATH edit and the handoff into setup) so it never blocks. The daemon, the olace command and the background service are installed either way. Ask the person whether they want ~/.olace/bin on their PATH permanently; the installer prints the line for their shell. 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. Ollama tags use :, LM Studio ids use /, --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 › Paired devices, 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, an OpenAI-compatible endpoint at http://127.0.0.1:5578/v1 for every local and paired model, loopback only. --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. 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.5:14b runs on the paired host called "Home PC"). The Bridge serves chat completions, completions and embeddings; it has no /v1/responses, so Codex CLI needs wire_api = "chat".

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, pairs.active, bridge.listening. 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 Bridge 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.