Administrator guide

Administrator quickstart

Prepare an administrator machine, choose one deployment path, and finish a new OpenCircle Server in the browser.

This page prepares the machine you will administer a new Server from. The default route stays plain on purpose: install the signed CLI, follow one deployment guide, create the first owner in the browser, then add API keys in Server admin.

A running container is not a finished deployment. It is finished only when the intended owner can sign in, the Server has one working model route, and you can complete one real reply from your Familiar.

1. Install the signed CLI

Choose the installer for your machine. It verifies OpenCircle's signed stable release manifest and installs the CLI under ~/.local/bin — no sudo, no Node or Bun, no source checkout.

Terminal

curl --fail --location \
  --output /tmp/install-opencircle \
  https://circle.example.com/download/cli/mac/arm64
chmod 755 /tmp/install-opencircle
/tmp/install-opencircle
~/.local/bin/opencircle --version

Add $HOME/.local/bin to your shell PATH if opencircle is not found afterward. Before following any guide, confirm its required command exists with opencircle help.

2. Prepare administrator custody

Before creating any infrastructure, open a password-manager entry for this Server. You will save:

the Server name and URL;
the permanent first-owner handle and account password;
a separate 6–8 digit approval PIN; and
every one-time recovery code shown after setup.

Keep the password, PIN, and recovery codes apart from each other, and never in shell commands, chat, screenshots, or source control.

For a first model-backed reply you need one key: Venice, OpenRouter, or OpenAI. For the fuller feature set, also plan for ElevenLabs, Tavily, Browser Use, and CloudConvert. Keys can be added after the Server is claimed, so nothing needs to sit in a config file yet.

3. Choose one deployment guide

Your first OpenCircleThe shortest path to a private Server on a Mac with Docker Desktop.Deploy with Docker ComposeRun a Compose stack locally or on an SSH-accessible Docker host.Deploy OpenCircle on RailwayUse the official template in a Railway workspace you control.

Follow one guide start to finish. If a terminal or browser tab closes partway through, use that guide's resume command rather than starting a second stack.

4. Create the first owner in the browser

When deployment opens the claim journey, confirm the browser is on the expected Server and that the address begins with /claim. Choose the permanent account password, set a separate approval PIN, complete setup once, and save every recovery code in your password manager.

Success ends in the Server Guide. Sign in again as the same owner before you trust it; a green health check alone does not prove ownership is complete.

5. Add API keys and prove the Server is useful

Sign in as an Owner or Admin, open Server admin → API Keys, add and validate your keys, then connect a client using your deployment guide or Connect clients.

Complete one real model-backed reply, sign out, and sign back in as the same owner. That confirms the Server is owned, recoverable, connected to a usable model route, and ready for day-two administration.

Optional automation

Automation is for administrators who need repeatable, noninteractive deployment; it is not required for the browser-first path above. Local and remote Compose automation lives in Deploy with Docker Compose; hosted automation lives in Railway automation.