Skip to content

Deploy OpenCircle

Your first OpenCircle

From a Mac to a Familiar of your own. Install OpenCircle, make it yours, and create your first piece of work together.

This walkthrough takes a Mac with Docker Desktop to a working OpenCircle Server, a Familiar with a character of its own, and your first saved document. Follow the steps in order, then explore the other guides.

Our example owner is Ada. Her Server is Ada's Studio and her first project is a neighborhood seed library. These are just examples — pick your own name, your own Familiar, and something you actually want to make.

Everything in this walkthrough runs on the same Mac. Docker runs the Server and its databases; your data stays on this machine. For a Server your phone or teammates can reach, follow the Railway guide instead.

1. Get Docker ready

Install or open Docker Desktop and wait for the engine to start, then confirm both pieces answer in Terminal:

Terminal

docker version
docker compose version

2. Install OpenCircle and start your server

Pick the installer that matches your Mac's chip, then check Apple menu → About This Mac if you are unsure:

Apple silicon

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

Intel

curl --fail --location \
  --output /tmp/install-opencircle \
  https://circle.example.com/download/cli/mac/x64
chmod 755 /tmp/install-opencircle
/tmp/install-opencircle

Create a profile for this Server and start it. The first run can take a few minutes; leave the command running while it starts the containers and opens setup in your browser.

Terminal

~/.local/bin/opencircle profile add ada-studio \
  --transport=local --lifecycle=compose \
  --instance-id=ada-studio --yes
~/.local/bin/opencircle deploy \
  --profile ada-studio --owner-mode claim --finish guide

3. Create your owner account

  1. Choose a sign-in handle and select Continue.
  2. Confirm the username and select Create account.
  3. Choose a strong password and save it in your password manager.
  4. Enter a display name and a separate 6–8 digit approval PIN, then select Complete setup.
  5. Save the one-time recovery codes somewhere private, then open the Server Guide.

Your password signs you in, your PIN approves sensitive actions, and your recovery codes get you back in if you lose the other two. Keep all three private.

4. Name your server and connect a model

Open Configure server, give it a recognizable name, and save. Then choose API Keys in the Server Guide. The minimum is one key — Venice, OpenRouter, or OpenAI — which together cover chat, embeddings, and image generation. The recommended set for every documented function adds ElevenLabs, Tavily, Browser Use, and CloudConvert.

5. Meet your Familiar

Return to the Server Guide and choose the button that opens chat. Try a first message such as: "Hi, I'm Ada. I'm planning a little seed library that opens on Saturdays. Help me work out what makes it worth a visit." Leave the conversation and come back — your message should still be there.

6. Make your Familiar yours

Open Settings → My Agents and choose to customize your Familiar. Describe the character you want to work with, pick a name and an appearance, and choose a voice if you configured one. These preferences shape personality only — they never grant access to anyone else's rooms or private memory.

Day two

Keep Docker Desktop running while you use this Server. Your account, conversations, and workspace documents live in its persistent volumes.

Check the server

~/.local/bin/opencircle status --profile ada-studio

Stop without deleting your data

~/.local/bin/opencircle destroy --profile ada-studio

Start the same server again

~/.local/bin/opencircle restart --profile ada-studio --full

For updates, follow Upgrade safely. Before your work becomes irreplaceable, set up backup and restore.