Documentation Index
Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt
Use this file to discover all available pages before exploring further.
AcornOps separates the operator experience, platform state, run execution, model/tool access, and workload-cluster access into distinct components. That separation keeps public traffic narrow and lets workload clusters connect outbound only.
System overview
Component responsibilities
| Component | Responsibility | Public exposure |
|---|
| Management console | Workspace, cluster, member, tool, and session user experience | https://console.acornops.dev/ |
| Control plane | Auth, workspaces, clusters, agent WebSockets, run state, webhooks, API authorization | https://acornops.dev/api/v1 |
| Execution engine | Run lifecycle, orchestration loop, event emission, cancellation, tool-call coordination | Internal only |
| LLM gateway | Provider routing, run-scoped model access, MCP registry, secret lookup, gateway auditing | Internal only |
| k8s agent | Workload-cluster snapshots, logs, and builtin Kubernetes tool execution | Outbound only |
Runtime flow
- An operator signs in through OIDC and uses the management console with a cookie-backed control-plane session.
- The operator creates a workspace, registers a cluster, and installs the generated k8s agent command into the workload cluster.
- The k8s agent authenticates with its agent key and opens an outbound WebSocket to the control plane.
- The agent sends heartbeats, capability metadata, and snapshots. The control plane persists cluster state and synchronizes builtin tools into the LLM gateway.
- When an operator sends a troubleshooting message, the control plane creates a run and dispatches it to the execution engine.
- The execution engine fetches run context from the control plane, streams model requests through the LLM gateway, and calls allowed tools.
- The control plane records run events and streams them back to the management console.
Auth and trust boundaries
AcornOps uses separate credentials for separate trust boundaries:
| Channel | Credential |
|---|
| Browser to control plane | Session cookie |
| Control plane to execution engine | EXECUTION_ENGINE_DISPATCH_TOKEN |
| Execution engine to control plane | ORCH_SERVICE_TOKEN |
| Control plane to LLM gateway admin API | LLM_GATEWAY_ADMIN_TOKEN |
| Execution engine to LLM gateway runtime API | Control-plane-signed run JWT |
| k8s agent to control plane | Cluster agent key |
Workspace and role model
A workspace owns members, clusters, MCP server settings, tool settings, sessions, runs, and webhooks. Server responses include role-derived permissions so clients can render actions without reimplementing authorization rules.
| Role | Typical capabilities |
|---|
owner | Manage workspace, owners, admins, clusters, tools, MCP servers, keys, read-only runs, and read-write runs |
admin | Manage non-owner members, clusters, tools, MCP servers, keys, read-only runs, and read-write runs |
operator | Create sessions, create read-only runs, read logs when allowed, cancel runs |
viewer | Read workspace, cluster, session, and run data |
Data ownership
| Data | Owner |
|---|
| Workspaces, members, clusters, sessions, runs, invitations, webhooks | Control plane |
| Run reservations and worker coordination | Execution engine with Redis |
| Provider credentials, MCP registry, gateway request records | LLM gateway |
| Live Kubernetes discovery and builtin tool behavior | k8s agent |
High availability posture
Management console, execution engine, and LLM gateway can run with multiple replicas when backed by external Postgres and Redis. The default platform chart sets the control plane to one replica because WebSocket routing and background scheduling are process-local.
The workload-cluster agent supports active-passive high availability through Kubernetes Lease leader election. When replicaCount is greater than one, enable leader election so exactly one agent runtime connects at a time.
