Skip to main content

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 deployment has two independent steps: deploy the central platform, then connect each workload cluster with the k8s agent.

​
Kubernetes

Use the acornops-platform Helm chart to deploy the central platform into a Kubernetes cluster. The chart deploys:
  • management console,
  • control plane,
  • execution engine,
  • LLM gateway,
  • database migration Jobs.
Postgres and Redis are operator-provided. The chart references an existing Kubernetes Secret instead of templating secret values into Helm values.

​
Required platform inputs

Prepare these inputs before installing the chart:
InputNotes
Public hostDefaults to acornops.dev for API routes.
Console hostDefaults to console.acornops.dev.
TLS secretReferenced by the ingress configuration.
External PostgresUsed by control plane and LLM gateway.
External RedisUsed by control plane, execution engine, and LLM gateway.
Existing secretDefaults to acornops-platform-secrets.
OIDC clientRedirects back to the control plane callback route.
LLM provider keyAt least one enabled provider needs credentials.
Example install: 
helm upgrade --install acornops-platform oci://ghcr.io/acornops/charts/acornops-platform \
  --namespace acornops-platform \
  --create-namespace \
  --values values.prod.yaml

​
Production exposure

Expose only the management console and control-plane public routes:
  • https://console.acornops.dev/
  • https://acornops.dev/api/v1
  • wss://acornops.dev/api/v1/agent/connect
Keep execution engine and LLM gateway private to the platform network.

​
Replicas

The chart defaults to multiple replicas for stateless or Redis-coordinated services where supported:
ComponentDefault posture
Management consoleMultiple replicas
Execution engineMultiple replicas with Redis-backed run reservation
LLM gatewayMultiple replicas with external Postgres and Redis
Control planeSingle replica by default
Run the control plane as one replica unless your deployment has distributed WebSocket routing and scheduler coordination.

​
VM Compose

Use the VM Compose stack for a single-machine central platform installation. This path is useful for smaller environments and production-style testing with separate Kubernetes workload clusters. Typical flow: 
cp env/vm/.env.example env/vm/.env.prod
task prod-up
Before starting the stack:
  • Generate unique internal service tokens and encryption keys.
  • Set production hostnames and OIDC settings.
  • Point database and Redis settings at durable services.
  • Pin image tags instead of using mutable tags.
  • Confirm the reverse proxy terminates TLS for the console and API hosts.
Database migrations run before services start. Treat migration failures as deployment blockers.

​
Workload clusters

Each workload cluster gets the acornops-k8s-agent Helm chart. Register the cluster in the management console, then run the generated install command returned by the control plane. The agent:
  • connects outbound to the control plane,
  • authenticates with the generated agent key,
  • reports heartbeats and snapshots,
  • advertises builtin Kubernetes tools,
  • executes allowed tool calls during troubleshooting runs.
Workload clusters do not need public inbound access.

​
Public documentation

The public documentation site is hosted by Mintlify at https://docs.acornops.dev/. Connect the docs repository in the Mintlify dashboard, install the Mintlify GitHub App for that repository, and deploy from the branch that contains docs.json. If the docs live inside a larger repository, configure the docs subdirectory in Mintlify Git settings. If they live in their own repository, keep docs.json at the repository root. The AcornOps platform edge does not serve docs itself. Legacy /docs paths on acornops.dev should redirect to the matching page on docs.acornops.dev.

​
Validation

Before promoting a deployment, verify:
  • the management console loads from https://console.acornops.dev/,
  • OIDC login returns to the expected callback route,
  • GET /api/v1/me returns the current user from the same host used by the management console session,
  • the first workspace can be created,
  • a registered k8s agent shows as connected,
  • a read-only troubleshooting run can stream events to the management console,
  • internal execution-engine and LLM-gateway endpoints are not publicly reachable.