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

# Architecture

> The four parts of Kubox, and the two ways to build a cluster.

Kubox has four parts. Most commands make sense once you can place them.

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#ecf5e3','primaryBorderColor':'#254d41','primaryTextColor':'#254d41','lineColor':'#254d41','edgeLabelBackground':'#ffffff','tertiaryColor':'#ffffff','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
flowchart TD
  You["You<br/>kubox CLI"] --> Console["Console<br/>app.kubox.cloud"]
  You --> Plane
  Console --> Plane["Management plane<br/>builds and tracks clusters"]
  Plane --> Account["Cloud account<br/>your AWS account"]
  Account --> C1["Cluster"]
  Account --> C2["Cluster"]
  You -. "kubox admin, no plane" .-> Account
```

## The four parts

| Part | What it is | Who owns it |
| - | - | - |
| **Console** | Where you sign in, create API keys, and read usage. | Kubox, or you if self-hosted |
| **Management plane** | Builds your clusters and keeps track of them. | Kubox, or you |
| **Cloud account** | Your AWS account, connected so the plane may build inside it. | Always you |
| **Cluster** | A Kubernetes cluster Kubox built, or an existing one it adopted. | Always you |

The division that matters: **the plane decides, your account holds.** Your clusters, their build state, and the keys that protect it live in your AWS account. Revoke the build role and Kubox stops managing them. It never held a copy.

## The normal path

Four commands take you from nothing to a running cluster.

<Steps>
  <Step title="Sign in">
    ```bash theme={null}
    kubox login
    ```

    Signs in to a console and stores a session on this machine. See [`kubox login`](/reference/cli/kubox_login).
  </Step>

  <Step title="Create the boundary in your AWS account">
    ```bash theme={null}
    kubox cloud bootstrap aws
    ```

    Run this as an AWS administrator. It sets the limits Kubox works inside, and creates the identity it connects as. See [`kubox cloud bootstrap`](/reference/cli/kubox_cloud_bootstrap).
  </Step>

  <Step title="Connect the account">
    ```bash theme={null}
    kubox cloud connect aws production
    ```

    Creates the role Kubox builds with, plus somewhere to keep build state and the keys to protect it — all in your account. See [`kubox cloud connect`](/reference/cli/kubox_cloud_connect).
  </Step>

  <Step title="Create a cluster">
    ```bash theme={null}
    kubox cluster create -f cluster.yaml
    kubox cluster status <name>
    ```

    The first command submits the request and returns before the cluster is ready. The second reports progress. See [`kubox cluster create`](/reference/cli/kubox_cluster_create).
  </Step>

  <Step title="Reach it with kubectl">
    ```bash theme={null}
    kubox cluster connect
    ```

    Adds the cluster to your kubeconfig. Access uses your Kubox sign-in, so sign in again when it expires. See [`kubox cluster connect`](/reference/cli/kubox_cluster_connect).

    From here it is an ordinary Kubernetes cluster — your existing manifests, operators, and tools work unchanged. Kubox provisions the cluster; deploying your application is still your job.
  </Step>
</Steps>

## The direct path

`kubox admin` drives a cloud or a cluster from your machine with the credentials you already hold, with no management plane involved:

```bash theme={null}
kubox admin create -f cluster.yaml
kubox admin delete -f cluster.yaml
```

It is the same build, started from a different place. Use `admin` when the normal path cannot help:

* a cluster no plane manages
* the first plane, before one exists
* a failure you need to get underneath

[Hello-World AWS Cluster](/hello-world-aws) walks the direct path end to end, because it needs no plane.

<Note>
  Both paths produce the same cluster. The difference is who holds the credentials and who tracks the result.
</Note>

## Where to go next

<CardGroup cols={3}>
  <Card title="Management plane" icon="tower-control" href="/concepts/management-plane">
    What a plane owns, and when you need your own.
  </Card>

  <Card title="Cloud accounts" icon="shield-halved" href="/concepts/cloud-accounts">
    The trusted boundary, and what Kubox can and cannot do in your account.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli/overview">
    Every command, option, and consequence.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.