Administrator guide
Configure an instance
Keep topology, setup inputs, and managed runtime state in their own separate authorities.
OpenCircle uses three different configuration authorities. Treating them as one giant environment file is how secrets leak and instances become impossible to reason about.
| Authority | Owns | Must not own |
|---|---|---|
| ~/.opencircle/profiles/<name>.toml | Transport, lifecycle, instance identity, endpoint, SSH and TLS policy | Provider keys or owner passwords |
| ~/.config/opencircle/deploy.toml | First-owner inputs, selected provider secrets, optional initial Familiar choices | Ports, Compose identity, database URLs, or generated runtime state |
| Managed config/instance.env | Runtime configuration written by OpenCircle's own deployment tooling | Hand-maintained setup templates or source-control defaults |
Profiles first
Profiles are deliberately non-secret. Inspect the active one before every mutation:
Terminal
opencircle profile current opencircle status
profile current identifies the selected topology and endpoint; status reports Compose state and best-effort setup health. Neither command proves a model-backed reply actually works.
Keep setup input outside Git
The setup file uses schema version 1, must be mode 0600, and must live outside a Git worktree. Reference secrets from the environment rather than embedding their values:
deploy.toml
schemaVersion = 1
[admin]
handle = "operator"
displayName = "OpenCircle Operator"
password = { fromEnv = "OPENCIRCLE_ADMIN_PASSWORD" }
pin = { fromEnv = "OPENCIRCLE_ADMIN_PIN" }
[[providers]]
key = "OPENAI_API_KEY"
value = { fromEnv = "OPENAI_API_KEY" }
[familiar]
mode = "skip"The supplied password becomes the owner's permanent sign-in password; choose it deliberately and save it before deployment, since first sign-in does not force a replacement. The schema accepts zero providers, but any feature that calls a model still needs a usable one configured.
config/instance.env is secret-bearing deployment state written by OpenCircle's own tooling. Keep its mode at 0600 and never hand-edit it.
Verify the result
After any configuration change, confirm you are using the intended profile, sign in as the owner, and send your Familiar a message. A successful status check alone does not confirm sign-in and model access work.