Developer guide

Run OpenCircle from source

Choose a claimed daily-driver instance, or spin up an isolated named one without ending at an empty login screen.

A running Server isn't automatically useful for development. The usable state is a named instance with an owner, retrievable credentials, at least one working model route, and a client that can complete a real turn.

Inventory before you choose

opencircle dev list-instances
opencircle dev cleanup-instances --name feature-lab --json

The first command shows identity, project, ports, process state, and storage root. The cleanup check is report-only even with --yes — use it to see whether a named instance is local, active, protected, or safe to remove.

Then pick one path on purpose: reuse the claimed default instance for fast work against retained data, copy default into an isolated named instance when you need realistic data without touching the daily driver, or create a fresh named instance to test first-run and claim behavior.

Prerequisites

Install Docker and the Bun and Node versions this checkout expects, then install workspace dependencies with bun install. Building the desktop app may also need a Rust toolchain; the launcher prints what's missing.

Path A: reuse the claimed default instance

Stop the old process only after the inventory proves it belongs to this instance and you mean to replace it, then start the stack against the retained data:

opencircle server stop --instance default
OPENCIRCLE_PROFILE=source-default opencircle dev-stack --instance default --i-know-what-i-am-doing --electron

This can apply committed migrations to the retained database. Reconcile competing histories with the migration safety guide first.

Path B: copy default into an isolated named instance

The normal isolated path when default is already a usable install. The target must not already exist:

OPENCIRCLE_PROFILE=feature-lab opencircle dev-stack --instance feature-lab --copy-default --electron

This captures a bounded seed from default, builds separate databases, ports, and identity for the new instance, and carries over users, auth state, provider configuration, and artifacts — it never touches the source. Remove a named instance only after the cleanup check says it's local, stopped, and safe to delete:

opencircle dev delete-instance feature-lab --yes

Path C: create and claim a fresh named instance

Bring the isolated Server up first, claim it, record the login, and configure a model route before launching the desktop client. Keep the setup values — handle, password, PIN, and any provider key — in a mode-0600 secrets file, never invented on the spot and thrown away.