Skip to main content
AcornOps has two deployment layers:
  • The central platform, which runs the management console, control plane, execution engine, and LLM gateway.
  • A AgentK in each Kubernetes cluster that AcornOps should observe or operate on.
  • A AgentV on each Linux/systemd VM that AcornOps should observe.

​
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 a self-host deployment, expose operator-owned hostnames such as: Replace example.com with DNS names you control. The public demo uses https://console.demo.acornops.dev/ and https://api.demo.acornops.dev. 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 agent ownership, command routing, run/event coordination, execution-engine reservations, and gateway rate limits.
  • OIDC client configuration for browser sign-in. Username/password login and password reset are enabled by default, while self-service signup is disabled for production deployment configs. Configure SMTP before relying on password reset or enabling password signup in production.
  • LLM provider credentials for at least one enabled provider.
  • TLS certificates and ingress for your API and console hosts.
  • 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:
For VM Compose, prepare the production environment file and start the stack:
Pin image tags for long-running environments. Avoid mutable image tags for production-style installs.

​
5. Sign in and create a workspace

Open your management console URL, such as https://console.example.com/, and sign in through your configured OIDC provider or username/password auth. If no workspace exists for your account, the management console should prompt you to create one. A workspace groups:
  • members and roles,
  • Kubernetes clusters and VMs,
  • tool and MCP server settings,
  • troubleshooting sessions and run history,
  • webhook subscriptions.

​
6. Register a target

In the workspace, register a Kubernetes cluster or Linux VM. The control plane returns:
  • the target record,
  • an agent key,
  • generated install instructions.
Use the generated install command instead of assembling one manually. It includes the correct scope, package or service settings, and agent key handling for the registered target.

​
7. Verify the connection

After the agent starts, verify that the target 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. A healthy connected VM should report host resources, services, processes, ports, findings, metrics, and bounded logs. You can then:
  • review target inventory and findings,
  • inspect pod logs when your role allows it,
  • configure tool availability,
  • add remote MCP servers,
  • start a read-only troubleshooting session for VMs or a read-only/read-write troubleshooting session for Kubernetes based on your workspace role and target policy.
Remote MCP servers are discovery-first. Add the server connection, test discovery, then enable reviewed tools with read or write capability.