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 has two deployment layers:
  • The central platform, which runs the management console, control plane, execution engine, and LLM gateway.
  • A k8s agent in each workload cluster that AcornOps should observe or operate on.

​
1. Choose a platform target

Use Kubernetes for production-like installs. Use VM Compose when you want a smaller single-machine platform host for early operations testing.

Kubernetes

Deploy the central platform with the acornops-platform Helm chart.

VM Compose

Deploy the central platform with Docker Compose on one VM.

​
2. Prepare public routes

For the default production hostnames, expose:
SurfaceURL
Management consolehttps://console.acornops.dev/
Public docshttps://docs.acornops.dev/
Browser and control-plane APIhttps://acornops.dev/api/v1
Agent WebSocketwss://acornops.dev/api/v1/agent/connect
The management console host also proxies /api to the control plane for browser session flows. Execution engine and LLM gateway are internal services. Do not expose them through public ingress in production.

​
3. Prepare dependencies

Before deploying the central platform, prepare:
  • External Postgres for control-plane state and LLM-gateway state.
  • External Redis for control-plane run/event coordination, execution-engine reservations, and gateway rate limits.
  • OIDC client configuration for browser sign-in.
  • LLM provider credentials for at least one enabled provider.
  • TLS certificates and ingress for acornops.dev and console.acornops.dev.
  • A secret bundle for database URLs, Redis URLs, OIDC credentials, internal service tokens, and gateway secrets encryption.
See Configuration for the required secret keys and host settings.

​
4. Deploy the central platform

For Kubernetes, create the secret expected by the chart, then install the platform chart: 
helm upgrade --install acornops-platform oci://ghcr.io/acornops/charts/acornops-platform \
  --namespace acornops-platform \
  --create-namespace \
  --values values.prod.yaml
For VM Compose, prepare the production environment file and start the stack: 
cp env/vm/.env.example env/vm/.env.prod
task prod-up
Pin image tags for long-running environments. Avoid mutable image tags for production-style installs.

​
5. Sign in and create a workspace

Open https://console.acornops.dev/ and sign in through your configured OIDC provider. If no workspace exists for your account, the management console should prompt you to create one. A workspace groups:
  • members and roles,
  • workload clusters,
  • tool and MCP server settings,
  • troubleshooting sessions and run history,
  • webhook subscriptions.

​
6. Register a workload cluster

In the workspace, register a cluster. The control plane returns:
  • the cluster record,
  • an agent key,
  • generated install instructions.
Use the install command returned by the control plane. Do not hand-build the command from chart defaults, because namespace scope, release name, chart reference, and agent key handling are owned by the control-plane response.

​
7. Verify the connection

After the k8s agent starts, verify that the cluster shows as connected in the management console. A healthy connected cluster should report snapshots with resources, events, and metrics when the cluster metrics API is available. You can then:
  • review cluster inventory and findings,
  • inspect pod logs when your role allows it,
  • configure tool availability,
  • add remote MCP servers,
  • start a read-only or read-write troubleshooting session based on your workspace role.

​
Local development shortcut

Use the deployment repository for the full local stack: 
task install
task doctor
task local-up
task local-ps
Useful local variants include the Dex or Keycloak OIDC profiles and optional Vault-backed secret storage. Stop or reset the stack with: 
task local-down
task local-reset