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

Native access for AI agents

MCP runs inside the control plane.

Cixd serves eligible API operations as typed tools through POST /v1/mcp. Calls use the REST handlers, permissions, and audit path. Long-running operations can park and resume, and non-JSON files return as typed base64 resources.

Each agent uses a directory identity and revocable app password. Group membership supplies role-based access control (RBAC): tool discovery is filtered by permissions, and execution checks them again. The standard agent group grants reads and gateway access; writes require additional grants. MCP is disabled until an operator enables it.

Permissions apply to an area and verb. For example, services:write permits changes to both DNS records and DNS servers; a DNS-record-only role is not currently expressible. App passwords never satisfy identity:write, even for an administrator’s identity. The app password authenticates the request; directory membership determines its permissions.

Read the MCP setup and permission guide →

POST /v1/mcpdirectory identitiesgroup permissionsaudited calls

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.
Roles constrain automationUsers receive the union of their groups’ area-and-verb permissions. An app password can automate REST and MCP, but never writes identities or creates credentials.
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

One contract.Every client.