---
title: Quick start
description: Configure the kobe CLI, lease a cluster, and release it when done.
---

# Quick start

This path leases a Kubernetes cluster. For sandboxes, see [Sandbox](/docs/getting-started/sandbox). You need the [CLI](/docs/getting-started/installation) and an endpoint. If you are standing the operator up yourself, [deploy](/docs/getting-started/deploy) it first.

<Steps>
  <Step>
    **Point the CLI at the endpoint**

    `kobe target set` writes to `./.kobe.toml` in the current directory unless you pass `--global`. Use `--global` for an endpoint you want from any directory:

    ```sh
    kobe target set work --endpoint https://kobe.example.com --auth ssh --global
    kobe target use work
    ```

    Or open the interactive editor:

    ```sh
    kobe config
    ```
  </Step>
  <Step>
    **Authenticate**

    ```sh
    kobe login
    ```

    kobe supports SSH key auth (Ed25519 via your SSH agent), OIDC, and static bearer tokens. Login detects which methods the endpoint accepts.

    Over SSH or on a headless host, use device login instead of a local browser:

    ```sh
    kobe login --device
    ```

    Check what the endpoint offers:

    ```sh
    kobe status
    ```
  </Step>
  <Step>
    **Lease a cluster**

    ```sh
    kobe lease ci-small
    ```

    The CLI waits until the lease is `Bound`, writes a kubeconfig to
    `~/.kube/kobe-<pool>-<short-id>.yaml`, and prints the path, lease id, and expiry.

    Request a longer TTL (capped by the policy's `maxTtl`). The CLI default is `1h` if you omit `--ttl`:

    ```sh
    kobe lease ci-small --ttl 2h
    ```

    Write the kubeconfig somewhere else:

    ```sh
    kobe lease ci-small --kubeconfig /tmp/kube.yaml
    ```

    Name the lease so you can reuse it in CI:

    ```sh
    kobe lease ci-small --name pr-3835 --ensure
    ```

    `--ensure` extends the existing active lease of that name instead of failing on the duplicate.
  </Step>
  <Step>
    **Use the cluster**

    ```sh
    export KUBECONFIG=~/.kube/kobe-ci-small-<short-id>.yaml
    kubectl get nodes
    ```

    The cluster is isolated. Resources you create die with the lease.
  </Step>
  <Step>
    **Release**

    ```sh
    kobe release <lease-id>
    ```

    This destroys the instance and starts a replacement in the pool. Releasing early in CI lets the pool refill for the next job. If you do nothing, the server expires the lease at TTL and the kubeconfig stops working (the client cert uses the same TTL).
  </Step>
</Steps>

## One command around a job

`kobe with-lease` creates a cluster lease, sets `KUBECONFIG` for one command, heartbeat-extends the lease while the command runs, and releases on exit (success, failure, or signal):

```sh
kobe with-lease ci-small --ttl 1h -- kubectl get nodes
kobe with-lease ci-small -- make e2e
```

The pool must expose the `kubeconfig` capability. For sandboxes, use `kobe run` instead.

## Heartbeat without wrapping a command

```sh
kobe lease ci-small --keepalive
```

Re-extends by `--ttl` at half-TTL intervals until Ctrl-C or the policy ceiling.

## See what you hold

```sh
kobe status
```

Text output hides released and expired leases. Pass `--all` or `-o json` for the full inventory.

Extend an active lease:

```sh
kobe extend --ttl 30m
kobe extend pr-3835 --ttl 30m
```

Release everything this identity still holds, and drop local kubeconfigs kobe wrote:

```sh
kobe purge
kobe purge --orphans-only   # files whose leases are already gone
```