Before you begin
- A deployed or staged Orchestris Server release
- Access to the deployment environment and secret manager
- A documented public origin, database and backup plan, and owner for TLS configuration
Choose the instructions for your edition
| Concern | Community Edition | Licensed Private Deployment |
|---|---|---|
| Edition and limits | Fixed free mode: one organization and up to 8 organization users. | Entitlements come from the portal-signed license assigned to the deployment. |
| Database | The Docker image fixes SQLite at /data/orchestris.db for a single node. | SQLite or PostgreSQL according to the delivered topology; PostgreSQL is required for multi-node. |
| Licensing configuration | None. Do not add portal URL, deployment secret, self-hosted organization ID, or signing-key configuration. | Use the mode, portal URL, deployment secret, organization UUID, and stable cluster ID supplied or identified by the Private Deployment handoff. |
| Secret provisioning | The CE entrypoint generates the core secrets in /data/orchestris.env and preserves them with the data volume. | The operator's secret manager supplies deployment-unique values according to the release bundle. |
| Operations | Single container/node, persistent local volume, stopped-volume backups. | Runbook, backup, monitoring, ingress, database, Redis, and rotation responsibilities follow the deployment plan. |
- Concern
- Edition and limits
- Community Edition
- Fixed free mode: one organization and up to 8 organization users.
- Licensed Private Deployment
- Entitlements come from the portal-signed license assigned to the deployment.
- Concern
- Database
- Community Edition
- The Docker image fixes SQLite at /data/orchestris.db for a single node.
- Licensed Private Deployment
- SQLite or PostgreSQL according to the delivered topology; PostgreSQL is required for multi-node.
- Concern
- Licensing configuration
- Community Edition
- None. Do not add portal URL, deployment secret, self-hosted organization ID, or signing-key configuration.
- Licensed Private Deployment
- Use the mode, portal URL, deployment secret, organization UUID, and stable cluster ID supplied or identified by the Private Deployment handoff.
- Concern
- Secret provisioning
- Community Edition
- The CE entrypoint generates the core secrets in /data/orchestris.env and preserves them with the data volume.
- Licensed Private Deployment
- The operator's secret manager supplies deployment-unique values according to the release bundle.
- Concern
- Operations
- Community Edition
- Single container/node, persistent local volume, stopped-volume backups.
- Licensed Private Deployment
- Runbook, backup, monitoring, ingress, database, Redis, and rotation responsibilities follow the deployment plan.
Configure the settings your deployment owns
The platform installer or Private Deployment handoff supplies the starting configuration. Change only values owned by your deployment. Nested environment names use the ORCHESTRIS_ prefix and double underscores.
| Setting | Purpose | Operational rule |
|---|---|---|
| ORCHESTRIS_SERVER__HOST | Network address where the server listens. The CE container fixes this to 0.0.0.0. | Restrict access with container port publishing, the host firewall, and the proxy or ingress configuration. |
| ORCHESTRIS_SERVER__PORT | Listener port. The CE container uses 8080. | A different external port can map to container port 8080 without changing the server process. |
| ORCHESTRIS_SERVER__PUBLIC_BASE_URL | The HTTP(S) origin Chat and browsers use. | Use only scheme, host, and optional port. No credentials, path, query, or fragment. |
| ORCHESTRIS_CORS__API_ALLOWED_ORIGINS | Exact browser origins allowed to call client-facing API routes. | Use comma-separated exact origins. Do not use * in production. |
| ORCHESTRIS_CORS__ADMIN_ALLOWED_ORIGINS | Exact browser origins allowed to call administrative routes. | Set only the Admin application origins that need browser access. |
| ORCHESTRIS_LOGGING__LEVEL | Server log filter. | Use the least verbose level that supports operations; logs must not contain credentials or authorization headers. |
- Setting
- ORCHESTRIS_SERVER__HOST
- Purpose
- Network address where the server listens. The CE container fixes this to 0.0.0.0.
- Operational rule
- Restrict access with container port publishing, the host firewall, and the proxy or ingress configuration.
- Setting
- ORCHESTRIS_SERVER__PORT
- Purpose
- Listener port. The CE container uses 8080.
- Operational rule
- A different external port can map to container port 8080 without changing the server process.
- Setting
- ORCHESTRIS_SERVER__PUBLIC_BASE_URL
- Purpose
- The HTTP(S) origin Chat and browsers use.
- Operational rule
- Use only scheme, host, and optional port. No credentials, path, query, or fragment.
- Setting
- ORCHESTRIS_CORS__API_ALLOWED_ORIGINS
- Purpose
- Exact browser origins allowed to call client-facing API routes.
- Operational rule
- Use comma-separated exact origins. Do not use * in production.
- Setting
- ORCHESTRIS_CORS__ADMIN_ALLOWED_ORIGINS
- Purpose
- Exact browser origins allowed to call administrative routes.
- Operational rule
- Set only the Admin application origins that need browser access.
- Setting
- ORCHESTRIS_LOGGING__LEVEL
- Purpose
- Server log filter.
- Operational rule
- Use the least verbose level that supports operations; logs must not contain credentials or authorization headers.
Keep database and secret settings together
| Setting | Purpose | Private Deployment rule |
|---|---|---|
| ORCHESTRIS_DATABASE__URL | Selects SQLite or PostgreSQL. | Use the database connection from the delivery plan. Treat PostgreSQL URLs as secrets and never share one SQLite file between nodes. |
| ORCHESTRIS_ENCRYPTION__MASTER_KEY | Encrypts sensitive server data. | Use a unique 64-hex key from the secret manager. Do not rotate it without an approved data-migration procedure. |
| ORCHESTRIS_SECURITY__API_KEY_PEPPER | Protects stored API-key verification data. | Use a unique 64-hex value and keep it for the life of existing API keys. |
| ORCHESTRIS_SYNC__CURSOR_SECRET | Signs synchronization cursors. | Keep it stable across restarts and nodes; changing it invalidates outstanding cursors. |
| ORCHESTRIS_EMAIL_HASH_SALT and ORCHESTRIS_PII_HASH_SALT | Salt privacy-preserving hashes. | Generate independent stable values; do not reuse the encryption key. |
- Setting
- ORCHESTRIS_DATABASE__URL
- Purpose
- Selects SQLite or PostgreSQL.
- Private Deployment rule
- Use the database connection from the delivery plan. Treat PostgreSQL URLs as secrets and never share one SQLite file between nodes.
- Setting
- ORCHESTRIS_ENCRYPTION__MASTER_KEY
- Purpose
- Encrypts sensitive server data.
- Private Deployment rule
- Use a unique 64-hex key from the secret manager. Do not rotate it without an approved data-migration procedure.
- Setting
- ORCHESTRIS_SECURITY__API_KEY_PEPPER
- Purpose
- Protects stored API-key verification data.
- Private Deployment rule
- Use a unique 64-hex value and keep it for the life of existing API keys.
- Setting
- ORCHESTRIS_SYNC__CURSOR_SECRET
- Purpose
- Signs synchronization cursors.
- Private Deployment rule
- Keep it stable across restarts and nodes; changing it invalidates outstanding cursors.
- Setting
- ORCHESTRIS_EMAIL_HASH_SALT and ORCHESTRIS_PII_HASH_SALT
- Purpose
- Salt privacy-preserving hashes.
- Private Deployment rule
- Generate independent stable values; do not reuse the encryption key.
Validate configuration before starting
Use the configuration-check command from the installation guide or delivery handoff for the exact package you run. It must load the same environment files, mounted state, and secrets as the real service.
Direct-binary example for a matching handoff
orchestris-api --config-checkRun the direct-binary example only when the handoff installs orchestris-api on the command path. Community Edition users should use the complete platform-specific check linked below so image names, paths, volumes, and environment files are defined.
- A successful check prints orchestris-api configuration check passed and exits without starting the HTTP server.
- The check fails when required settings or secret relationships are missing.
- A passing check does not prove that providers, the licensing portal, email, the database server, or the public proxy are reachable. Verify those after startup.
Use Orchestris Admin for runtime configuration
Environment variables control server startup. Providers, models, users, groups, API keys, usage, and other day-to-day organization settings belong in Orchestris Admin. The paths below are relative to the Admin application origin, not the public website and not necessarily the API origin.
| Admin path | Use it for | Typical access |
|---|---|---|
| /providers | Provider credentials, protocols, discovery, model catalog, and verification. | Organization admin or server admin with an organization selected. |
| /model-aliases | Stable names that each target one backing organization model. | Organization admin or server admin with an organization selected. |
| /groups | Membership, model/alias grants, and daily token quotas. | Organization admin or server admin with an organization selected. |
| /users | Organization users, invitations, status, and user-specific quota overrides. | Organization admin or server admin with an organization selected. |
| /api-keys | Organization API-key policy, agent keys, allowlists, and daily token or daily cost budgets. Both usage counters refresh at the organization's local day boundary. | Organization admin or server admin with an organization selected. |
| /usage | Request, token, cost, latency, and export reporting. | Organization admin or server admin with an organization selected. |
| /ops | Local/system health and operational activity. | Server admin or an explicitly permitted local-diagnostics role. |
| /security | Deployment-level security settings exposed by the Admin application. | Global server admin. |
- Admin path
- /providers
- Use it for
- Provider credentials, protocols, discovery, model catalog, and verification.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /model-aliases
- Use it for
- Stable names that each target one backing organization model.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /groups
- Use it for
- Membership, model/alias grants, and daily token quotas.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /users
- Use it for
- Organization users, invitations, status, and user-specific quota overrides.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /api-keys
- Use it for
- Organization API-key policy, agent keys, allowlists, and daily token or daily cost budgets. Both usage counters refresh at the organization's local day boundary.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /usage
- Use it for
- Request, token, cost, latency, and export reporting.
- Typical access
- Organization admin or server admin with an organization selected.
- Admin path
- /ops
- Use it for
- Local/system health and operational activity.
- Typical access
- Server admin or an explicitly permitted local-diagnostics role.
- Admin path
- /security
- Use it for
- Deployment-level security settings exposed by the Admin application.
- Typical access
- Global server admin.
- Configure providers, models, and aliases
- Manage users and invitations
- Configure groups, access, and quotas
Secure public access
- Use trusted HTTPS for every non-loopback Chat, Admin, agent, and licensing-portal connection. Terminate TLS with the method defined by the platform guide or Private Deployment handoff.
- Set ORCHESTRIS_SERVER__PUBLIC_BASE_URL to the external origin clients actually use. Keep it consistent through initialization and runtime.
- Allow only exact browser origins in API and Admin CORS settings. CORS is a browser rule, not a replacement for authentication, firewalls, or network policy.
- Keep administrative and diagnostics origins private where possible. Do not publish database, Redis, or provider-management ports.
- If a reverse proxy supplies client-address headers, configure trusted proxies narrowly. An untrusted forwarding header must not decide security policy or rate-limit identity.
- Protect the /metrics endpoint behind an internal network or authenticated proxy if metrics are enabled; it is disabled by default.
The following example applies only to a handoff that runs the server binary directly and assigns TLS termination to that process. Container, system service, and reverse-proxy deployments must use their supplied startup configuration instead.
Direct-binary TLS example for a matching handoff
orchestris-api \
--enable-tls \
--tls-cert-path /run/secrets/tls-chain.pem \
--tls-key-path /run/secrets/tls-key.pemTreat secrets and backups as one recovery system
| Material | If it is lost or changed unexpectedly |
|---|---|
| Encryption master key | Encrypted provider credentials and other protected data may become unrecoverable. |
| API-key pepper | Previously issued API keys may no longer verify. |
| Sync cursor secret | Outstanding synchronization cursors become invalid and clients must recover or reset sync state. |
| JWT private/public keys | Existing access tokens and server identity verification can be disrupted. |
| Deployment secret | Licensed portal validation fails until the running deployment and portal record agree. |
| Database without matching secrets | A database-only restore can start but still leave encrypted or authenticated data unusable. |
- Material
- Encryption master key
- If it is lost or changed unexpectedly
- Encrypted provider credentials and other protected data may become unrecoverable.
- Material
- API-key pepper
- If it is lost or changed unexpectedly
- Previously issued API keys may no longer verify.
- Material
- Sync cursor secret
- If it is lost or changed unexpectedly
- Outstanding synchronization cursors become invalid and clients must recover or reset sync state.
- Material
- JWT private/public keys
- If it is lost or changed unexpectedly
- Existing access tokens and server identity verification can be disrupted.
- Material
- Deployment secret
- If it is lost or changed unexpectedly
- Licensed portal validation fails until the running deployment and portal record agree.
- Material
- Database without matching secrets
- If it is lost or changed unexpectedly
- A database-only restore can start but still leave encrypted or authenticated data unusable.
- Put the database and its matching keys and secrets in the same backup set.
- Encrypt backups at rest, restrict restore access, record retention, and test restores on an isolated network.
- Stop Community Edition before archiving its complete /data volume so the SQLite database, WAL files, and secrets are consistent.
- For PostgreSQL, use database-native consistent backup tooling and separately version the deployment's secret/key material.
- Before an upgrade, preserve a pre-upgrade recovery point and the prior pinned release. Do not assume an older binary can read a migrated database.
- Rotate one secret only through a documented product procedure that accounts for all data and clients depending on it.