---
title: "Connect a cluster"
canonical: "https://admiral.io/docs/get-started/connect-a-cluster"
description: "Connect a Kubernetes cluster to Admiral: sign up, install the CLI, and run a Kubernetes agent inside a local kind cluster - no cloud account needed."
---

# Connect a cluster

{/*
  OUTLINE / DRAFT. Step 1 of the walkthrough. Removes the biggest cliff (running an
  agent) by using local kind + the outbound-only model. End state: a registered,
  healthy Kubernetes agent that the next steps can target.
  */}

In this step you connect a Kubernetes cluster to Admiral by running a **Kubernetes agent** inside it. We use a local [kind](https://kind.sigs.k8s.io/) cluster so you need no cloud account.

## 1. Sign up and log in [#1-sign-up-and-log-in]

{/* TODO: hosted signup URL + `admiral login` flow (OIDC browser login -> session/token).
   Cross-ref /docs/guides/authentication-model once reframed. */}

## 2. Install the CLI [#2-install-the-cli]

{/* TODO: install steps (brew / curl / go install?) + `admiral version` check.
   Likely belongs partly in /docs/reference/cli and gets linked from here. */}

## 3. Create a local cluster [#3-create-a-local-cluster]

```bash
kind create cluster --name admiral-demo
kubectl cluster-info --context kind-admiral-demo
```

## 4. Register and run the agent [#4-register-and-run-the-agent]

<Steps>
  ### Register the agent with Admiral [#register-the-agent-with-admiral]

  Registering yields a token the agent uses to authenticate when it pulls work.

  <Tabs items="[&#x22;CLI&#x22;, &#x22;Web&#x22;]">
    ### CLI

{/* TODO: real command. Placeholder reflects the settled (target) Agent surface. */}

      ```bash
      admiral agent register --kind kubernetes --name admiral-demo
      ```
    
### Web

{/* TODO: web walkthrough - Agents -> New agent -> kind: kubernetes -> copy token.
         Add screenshots when the UI is stable. */}

      1. Open **Agents** on the web.
      2. Choose **New agent**, kind **Kubernetes**.
      3. Copy the issued token for the next step.
    

### Install the agent into the cluster [#install-the-agent-into-the-cluster]

  {/* TODO: the actual install mechanism is an OPEN decision (CLI-embedded Helm SDK
     vs generated manifest vs `helm install`) - see plg-onboarding.md "install-UX".
     Document whichever ships. Keep `helm` off the hard-requirement list if possible. */}

  <Tabs items="[&#x22;CLI&#x22;, &#x22;Web&#x22;]">
    ### CLI

```bash
      # TODO: one-command, token-in agent install into the current kube-context
      admiral agent install --token <TOKEN>
      ```
    
### Web

{/* TODO: web UI shows the copy-paste install command after registration. */}

      The web UI shows a copy-paste install command after you register the agent.
    

</Steps>

## 5. Verify it connected [#5-verify-it-connected]

<Tabs items="[&#x22;CLI&#x22;, &#x22;Web&#x22;]">
  ### CLI

```bash
    admiral agent list
    ```

    A healthy agent reports a recent heartbeat.
  
### Web

The agent shows as **connected** in the Agents list once it dials in.
  

## Next [#next]

- [2. Applications & environments](https://admiral.io/docs/get-started/applications-and-environments.md): Create a source, an app, and dev + prod environments