> ## 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.

# Quickstart

> Prepare the AcornOps platform, sign in, and connect your first target

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.

<CardGroup cols={2}>
  <Card title="Kubernetes" icon="dharmachakra" href="/deployment#kubernetes">
    Deploy the central platform with the `acornops-platform` Helm chart.
  </Card>

  <Card title="VM Compose" icon="server" href="/deployment#vm-compose">
    Deploy the central platform with Docker Compose on one VM.
  </Card>
</CardGroup>

## 2. Prepare public routes

For a self-host deployment, expose operator-owned hostnames such as:

| Surface                  | URL                                          |
| ------------------------ | -------------------------------------------- |
| Management console       | `https://console.example.com/`               |
| Public docs              | `https://docs.acornops.dev/`                 |
| Public control-plane API | `https://api.example.com/api/v1`             |
| Agent WebSocket          | `wss://api.example.com/api/v1/agent/connect` |

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](/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:

```bash theme={null}
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:

```bash theme={null}
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 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.