Engineer’s entry point

One contract.
Every client.

Cix exposes the host through a REST API. cixctl, the web dashboard, and your automation all speak to the same daemon and the same resource model.

The boundary

Use the interface the product uses.

The daemon is the only process with direct access to runtime and host primitives. Clients send intent over HTTP/JSON; the OpenAPI document defines the operations, fields, and responses that are actually implemented.

Open the OpenAPI contract

cixctlREST client

DashboardREST client

{ }Your toolOpenAPI

HTTP / JSON

ONE AUTHORITY · ONE CONTRACTcixdvalidate · persist · reconcile

Read first

Authenticate before reading protected state.

Cix keeps liveness public, but host state is protected once authentication is active. health, login, logout, and whoami remain available without a session; reads such as boot, containers, networks, storage, services, packages, and logs require the permission named by the API contract.

GET /v1/healthGET /v1/whoamiGET /v1/containerspermission:read

Change safely

Write intent, then read the effect back.

Mutations are ordinary REST requests: create or update a resource, then read the resulting state and its derived readiness. The CLI and dashboard do not have privileged side channels, so an integration can use the same evidence as the first-party clients.

curl -s http://cix-host/v1/health → {"status":"ok","auth_gating_active":false}

POSTPUTDELETEderived state

Authenticate writes

Permissions follow the contract.

Every operation declares one permission in OpenAPI. A session or app password receives the union of its groups; missing credentials return 401, while a valid identity without the required permission returns 403. App passwords are for automation and are sent as HTTP Basic credentials on each request.

POST /v1/login → {"token":"…","expires_in_seconds":900}

sessionsapp passwords401 / 403OpenAPI permissions

Integration boundaries

Automation gets the same truth.

Use the API for orchestration, but keep the product’s actual boundaries in view.

OpenAPI is authoritativeUse the versioned OpenAPI contract for exact schemas, status codes, and route names.
cixd owns side effectsClients express intent; the daemon validates, persists, reconciles, and drives Linux primitives.
Managed LDAP listeners are explicitLDAP server listener selection and ports are API-owned. A client’s TLS choice points to an enabled server listener, while a requested server restart is sequenced one provider at a time.
Containers are not VMsWorkloads use namespaces and cgroups. Device grants do not create a hypervisor isolation boundary.
Authentication is not optional once enabledPlan for a session token, admin-group bootstrap, refusal auditing, and physical or hypervisor recovery if credentials are lost.

Canonical references

Integrate from the source.

Use the human guide for orientation and OpenAPI for implementation.

Read the API guide

Open OpenAPI