> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Set up Ankra end to end: try the live playground, import or provision a Kubernetes cluster, build and deploy a stack, wire up GitOps and CI/CD, then operate it with AI - from the web UI, the ankra CLI, an MCP-connected agent, or your pipelines.

This guide walks you through setting up Ankra: trying it in the playground, connecting a cluster, building your stack, and using AI to manage your infrastructure. GitOps is optional - stacks deploy directly through the Ankra agent, and you can add a Git audit trail whenever you want it.

This guide uses the web UI; every step also works from the [CLI](/integrations/ankra-cli), an [MCP-connected agent](/platform/mcp-server), or your [CI/CD pipelines](/guides/pipeline-agents) - step 5 wires those up.

**What you need:** a Kubernetes cluster you can run `helm` against (EKS, GKE, AKS, k3s, minikube - anything), or nothing at all if you start in the playground.

***

## 0. Try the Playground (optional)

No cluster handy? Start in the **playground**: a real, writable, ephemeral Kubernetes environment we provision for you in about two minutes. It comes with a starter stack already deploying, so you can watch a real deploy land, then use the AI to ship something yourself.

<Steps>
  <Step title="Start the playground">
    On your first visit, choose **Try it in a live playground**. You can also start one later from **Clusters** → **Try Playground**.
  </Step>

  <Step title="Deploy something">
    Everything works: deploy stacks, browse resources, break things, ask the AI to fix them. The playground is yours alone.
  </Step>

  <Step title="Graduate to your own cluster">
    The playground expires after a few days (you'll get a heads-up). Everything you learned works identically on your own cluster - importing one takes a single helm command.
  </Step>
</Steps>

***

## 1. Connect a Cluster

Everything starts with a cluster. Import an existing one or provision a new managed cluster.

<Tabs>
  <Tab title="Import Existing Cluster">
    Import any Kubernetes cluster - EKS, GKE, AKS, on-prem, k3s, minikube, or kind.

    <Steps>
      <Step title="Create the cluster in Ankra">
        Go to **Clusters** and click **Import Cluster**. Give it a name.
      </Step>

      <Step title="Install the Ankra agent">
        Ankra generates a Helm command for your cluster. Run it wherever you have `kubectl` access:

        ```bash theme={null}
        helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
          --namespace ankra \
          --create-namespace \
          --set config.token="YOUR_UNIQUE_TOKEN"
        ```

        The agent connects your cluster to the platform securely. It works behind firewalls, NATs, and private networks.
      </Step>

      <Step title="Verify the connection">
        Your cluster appears in the dashboard within seconds. You now have full visibility into workloads, resources, and events.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Provision a Managed Cluster">
    Ankra provisions production-ready Kubernetes clusters (kubeadm with Cilium by default, or K3s) on Hetzner, OVHCloud, or UpCloud with automated networking, bastion hosts, and NAT gateways.

    <Steps>
      <Step title="Add cloud credentials">
        Go to **Credentials** and add your cloud provider API key (Hetzner, OVH, or UpCloud). Don't have a Hetzner account? [Sign up for Hetzner Cloud](https://www.hetzner.com/cloud) to get started.
      </Step>

      <Step title="Create a cluster">
        Go to **Clusters** → **Create Cluster**. Select your provider and configure:

        * **Region** - choose a datacenter location
        * **Node sizing** - control plane and worker node types
        * **Networking** - private network range and subnet
        * **Distribution and version** - kubeadm with Cilium is preselected (K3s is one click away); pick a supported Kubernetes version
      </Step>

      <Step title="Wait for provisioning">
        Ankra provisions the infrastructure, installs Kubernetes, configures networking, and connects the agent. The cluster is fully yours - if you disconnect from Ankra, everything keeps running on your cloud account.
      </Step>
    </Steps>

    <Tip>
      You can also provision clusters from the CLI: `ankra cluster hetzner create`, `ankra cluster ovh create`.
    </Tip>
  </Tab>
</Tabs>

***

## 2. Build Your Stack

A **Stack** is a collection of Helm charts, manifests, and variables that define your Kubernetes environment. Build stacks visually or with AI assistance.

<Steps>
  <Step title="Open the Stack Builder">
    Navigate to your cluster → **Stacks** → **Create Stack**. The visual canvas opens.
  </Step>

  <Step title="Add components">
    Click **+ Add** to compose your stack:

    * **Add-ons** - Helm charts like Prometheus, Grafana, NGINX Ingress, cert-manager
    * **Manifests** - custom Kubernetes YAML (namespaces, RBAC, ConfigMaps, CRDs)

    Drag components onto the canvas and connect them to define deployment order.
  </Step>

  <Step title="Or, use the AI Assistant">
    Press `⌘+J` and describe what you need:

    *"I need a monitoring stack with Prometheus, Grafana, and Loki for a production cluster with 30-day retention"*

    The AI recommends components, configurations, dependencies, and deployment order tailored to your cluster.
  </Step>

  <Step title="Configure and deploy">
    Click any component to edit its values. Use [variables](/concepts/variables) with `${{ ankra.variable_name }}` for environment-specific configuration. Click **Create Stack** to save and deploy.

    Deploys go directly through the Ankra agent - no Git repository or extra credentials required.
  </Step>
</Steps>

<Note>
  Stacks can be cloned across clusters - replicate a stack from dev to staging to production. See [Clone a Stack](/guides/clone-stack).
</Note>

***

## 3. Connect GitOps (optional)

Stacks deploy without Git. Connect a GitHub repository when you want version control, an audit trail, and CI/CD integration on top - every stack write is then also committed to your repository. This is where Ankra integrates with your existing CI/CD.

<Steps>
  <Step title="Connect your repository">
    Go to your cluster → **Settings** → **Integration**. Select a GitHub credential (or add one) and choose the repository where Ankra will store your cluster configuration.

    Ankra installs ArgoCD and the GitOps engine on your cluster automatically.
  </Step>

  <Step title="Your stacks are now in Git">
    Every stack you build is exported as Helm values and manifests to your repository under `clusters/{cluster-name}/`. Changes in either direction sync automatically.
  </Step>

  <Step title="Wire up your CI/CD pipeline">
    Your existing CI pipeline can now deploy through Ankra:

    1. CI builds a container image and pushes to your registry
    2. CI commits the new image tag to the GitOps repo
    3. Ankra detects the change and deploys to your cluster

    ```mermaid theme={null}
    flowchart LR
        A[git push] --> B[CI builds image]
        B --> C[Update GitOps repo]
        C --> D[Ankra syncs cluster]
    ```

    See the full walkthroughs for [GitHub Actions](/guides/cicd-pipeline) or [GitLab CI](/guides/gitlab-cicd-pipeline). For app repos, [Applications (closed beta)](/concepts/applications) generates the Dockerfile, Helm chart, and pipeline for you.
  </Step>

  <Step title="Monitor sync status">
    Go to your cluster → **Settings** → **GitOps** to view sync status, history, and any errors. Every sync is tracked with commit SHA, trigger source, and timestamp.
  </Step>
</Steps>

### GitOps file format

For advanced setups, define your clusters declaratively using `include` paths to keep configuration modular:

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
spec:
  git_repository:
    provider: github
    credential_name: my-credential
    branch: main
    repository: my-org/infra-gitops
  stacks:
    - name: platform-stack
      manifests:
        - include: manifests/
      addons:
        - include: addons/
```

Different teams can own different YAML files in the same repo - no merge conflicts, no monolithic configs. The full schema is in the [ImportCluster YAML reference](/reference/importcluster).

***

## 4. Manage with AI

With your cluster connected and stacks deployed, Ankra's AI capabilities unlock powerful management and debugging workflows.

### Ask the AI anything

Press `⌘+J` from anywhere in the platform. The AI is page-aware - it automatically knows what you're looking at. Three modes control how much it can do: **Ask** answers read-only, **Agentic** confirms each change before acting, and **Plan** lets you approve a plan once and watch it execute.

| You're viewing | What the AI already knows                                             |
| -------------- | --------------------------------------------------------------------- |
| A crashing pod | Its logs, events, manifest, resource usage, and parent deployment     |
| A deployment   | All replicas, rollout status, associated services, and recent changes |
| A stack        | Installed add-ons, Helm values, deployment history, and dependencies  |

**Try these:**

* *"Why is my pod crashing?"*
* *"Scale this deployment to 5 replicas"*
* *"What changed in the last hour that could cause 503 errors?"*
* *"Create a Redis stack with persistence enabled"*

### Enable proactive AI Insights

Navigate to **Organisation Settings** → **General** → toggle **Proactive AI Insights**. The AI continuously scans your clusters and surfaces issues with root cause analysis, remediation commands, and MTTR analytics before they become incidents.

### Set up alerts with AI analysis

Configure [alert rules](/guides/alerts) on your cluster. When alerts trigger, Ankra's AI automatically collects cluster data and generates structured incident reports with root cause, affected resources, and recommended actions.

***

## 5. Take Ankra to Your Tools

The same tool registry behind `⌘+J` is available outside the browser - to your terminal, your editor's AI agent, and your pipelines. **No browser automation required.**

<Tabs>
  <Tab title="CLI">
    Install, sign in, and hand tasks to the AI from your terminal:

    ```bash theme={null}
    bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
    ankra login
    ankra chat "why is the payments pod crashing?" --cluster prod
    ankra chat "scale the api deployment to 5 replicas" --cluster prod --mode agent
    ```

    `--mode ask` stays read-only (plus safe creations); `--mode agent` lets it act. For headless or CI use, set the `ANKRA_API_TOKEN` environment variable instead of `ankra login`. See the [Ankra CLI guide](/integrations/ankra-cli).
  </Tab>

  <Tab title="MCP (Claude, Cursor)">
    Point any MCP client at Ankra's remote server and it gets the full tool surface (clusters, workloads, logs, stacks, provisioning) gated by `mcp:read` / `mcp:write` scopes.

    ```bash theme={null}
    # Claude Code - register once, then authenticate with /mcp
    claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp
    ```

    Then install Ankra's curated Agent Skills into your editor - `ankra skills install` for Cursor (default) or `ankra skills install --editor claude-code` for Claude Code.

    See the [MCP Server guide](/platform/mcp-server) for Claude desktop/web, Cursor, tokens, and OAuth, and the [MCP Tool Reference](/platform/mcp-tools) for every tool.
  </Tab>

  <Tab title="CI/CD">
    Your pipelines deploy through the GitOps image-bump flow from step 3. Beyond deploys, any plain CI job becomes a **pipeline agent** by calling the CLI:

    ```yaml theme={null}
    - run: bash <(curl -sL https://github.com/ankraio/ankra-cli/releases/latest/download/install.sh)
    - env:
        ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}
      run: ankra chat --cluster prod -o json "Review this repo's cluster YAML against the live cluster"
    ```

    See [Pipeline Agents](/guides/pipeline-agents) for PR review, deploy watching, and scheduled health checks, the [GitHub Actions](/guides/cicd-pipeline) and [GitLab CI](/guides/gitlab-cicd-pipeline) pipeline guides, or the [Terraform provider](/integrations/terraform) for infrastructure-as-code.
  </Tab>
</Tabs>

***

## What's Next

<CardGroup cols={2}>
  <Card title="Build a Monitoring Stack" icon="chart-line" href="/guides/monitoring-stack">
    Deploy Prometheus, Grafana, and Loki with AI assistance.
  </Card>

  <Card title="Pipeline Agents" icon="code-branch" href="/guides/pipeline-agents">
    PR review, deploy watching, and scheduled health checks from plain CI jobs.
  </Card>

  <Card title="MCP Server" icon="plug" href="/platform/mcp-server">
    Connect Claude, Cursor, and other MCP clients with scoped access to 169 platform tools.
  </Card>

  <Card title="AI Assistant" icon="robot" href="/platform/ai-assistant">
    Deep dive into AI-powered troubleshooting, stack building, and incident triangulation.
  </Card>

  <Card title="Variables & Secrets" icon="key" href="/concepts/variables">
    Parameterise your stacks with organisation, cluster, and stack-level variables.
  </Card>

  <Card title="Hermes" icon="comments" href="/integrations/hermes">
    Run Ankra's autonomous infrastructure agent from Slack, Discord, or Telegram.
  </Card>
</CardGroup>

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.