client-api is the single public backend used by Individual Open Source and Private Cloud. OpenLeash Cloud wraps the same surface through cloud-client-api; it does not fork the core plugin, policy, or agent-event semantics.
It evaluates agent events, records audit trails, stores pending approvals, serves mobile state, manages update metadata, and exposes the core API that OpenLeash Cloud wraps for hosted customers.
installed hooks ───────────────► configured client-api
provider traffic ─► local proxy ─► desktop edge ─► plugin containers
│
└────────► configured client-api
client-api ──► Postgres policy, plugin settings, audit, approvals, account/org state
| Mode | Role |
|---|---|
| 🧑💻 Individual Open Source | Runs locally with the real public Postgres schema for one user. |
| 🏢 Private Cloud | Customer-hosted managed API. |
| ☁️ OpenLeash Cloud | Wrapped by cloud-client-api for hosted tenancy and cloud controls. |
- Receive normalized events from installed hooks, the desktop provider edge, and retrospective provider connectors
- Evaluate actions against policy and model providers
- Store audit, evaluations, MCP calls, skills, triggers, and pending approvals
- Run the ordered OpenLeash plugin pipeline for prompts, tools, agent responses, startup, sessions, MCP inventory, and skill changes
- Serve mobile approval and account state
- Enroll managed endpoints with deployment tokens
- Apply Postgres migrations safely through
schema_migrations - Provide extension points for hosted/private wrappers
GET /v1/client/notifications includes versioned attentionEvents for pending
approvals, native questions, plan reviews, blocked actions, and completed
turns. Desktop and mobile resolve the same durable decision through the client
or mobile decision endpoint. An allow resolution may include a bounded,
structured response; the waiting hook receives that payload and the agent
adapter translates it into the agent's native answer format.
This path is deliberately backend-owned. Individual Open Source uses its local
client-api and Postgres, Private Cloud uses the customer-hosted service, and
OpenLeash Cloud uses the same public API through its thin cloud wrapper. The
desktop local server mirrors the contract only for setup, development, and
legacy relay behavior; it is not a separate product backend.
Core protections are implemented as pipeline plugins. Each plugin declares a manifest with metadata, events, permissions, settings, effects, ordering, and execution environment. Implementations use stable runtime capabilities instead of importing OpenLeash internals.
OpenLeash resolves installation and configuration before invoking plugin code. Individual users can configure a plugin globally, for an agent kind, or for an exact authenticated/enrolled agent runtime. Organization admins independently control mandatory installation, default enablement, optional employee installs, and configuration locking; organization profiles apply across employees, followed by permitted user profiles. A mandatory plugin cannot be removed or disabled by an employee, but it remains configurable when the admin leaves settings unlocked.
Plugins may publish typed, expiring annotations, progress, and ambient status through the Island capability. OpenLeash owns rendering and navigation; plugins never send UI code. See docs/PLUGIN_ISLAND.md.
Developer docs live in src/plugins/README.md. First-party plugin examples live as one public repository per plugin under the open-leash/plugin-* pattern.
npm install
docker compose up -d postgres
python3 migrate.py --target local --scope core --apply --yes
npm run dev:client-apiHealth:
curl http://localhost:9318/healthRecommended full-mode runner:
python3 run.pyclient-api owns the public self-hosted schema. It must be migrated before client-api or dashboard-api starts.
Fresh self-hosted Postgres database:
python3 migrate.py --target custom --database-url 'postgres://...' --scope core --apply --yesUpgrade an existing self-hosted deployment:
python3 migrate.py --target custom --database-url 'postgres://...' --scope core --backup-apply --yesRead-only status:
python3 migrate.py --target custom --database-url 'postgres://...' --scope core --status --yesOperators should run migrations as a one-shot deployment job, not as API startup logic. Migrations are tracked in schema_migrations with checksums and timestamps. Never edit an applied migration; add a new forward migration that performs all needed schema and data changes.
For production, use separate database roles:
openleash_opsis the schema owner and migration/admin login. Operators may use it from tools such as DBeaver.openleashis the API runtime login. It receives table, sequence, and routine privileges, but normal API processes do not need schema ownership.
Run production migrations with the openleash_ops connection string. Migration 0032_database_role_contract establishes default privileges so objects created by later migrations are immediately usable by openleash without one-off grants. Keep the runtime and operations connection strings in separate secrets.
OpenLeash supports tenant BYOK evaluation keys for OpenAI, Anthropic/Claude, and DeepSeek.
Keys are stored encrypted in organization config. Evaluation can run through:
- Tenant BYOK provider
- OpenLeash-managed provider
- Deterministic fallback for local/dev safety
- Tokens are hashed before storage.
- Postgres migrations are checksummed and tracked.
- Destructive DB changes should ship with explicit migration review.
- Public core behavior belongs here; OpenLeash-hosted-only behavior belongs in cloud wrappers.