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

# Bast

> Pick your boxd machines from Bast's SSH host list, and create, stop, start, fork, and delete them from its TUI or CLI.

![The Bast logo inside the boxd card.](https://mintcdn.com/azin/7IWa9uzq2xw7Urj2/images/boxd-x-bast.png?fit=max\&auto=format\&n=7IWa9uzq2xw7Urj2\&q=85\&s=765e62daef216d1c48437b20cca8ec0c)

[Bast](https://bast.sh) is an open-source SSH host picker and key manager for the terminal, built on OpenSSH. It reads your existing SSH config, manages keys, and syncs hosts from cloud providers into one list.

The [boxd sync provider](https://github.com/ellipse-software/bast/pull/112) imports your boxd machines as SSH hosts. From Bast's TUI or CLI you can then create, stop, start, restart, fork, and delete them. Bast works through the boxd CLI on your computer and stores no boxd token.

## Set up

**1. Install Bast**

boxd support ships in the first Bast release after v0.11.0. Then the installer gets it:

```bash theme={"theme":"github-dark"}
curl -fsSL https://bast.sh/install | sh
```

Until then, build it from the main branch. It needs Go 1.26:

```bash theme={"theme":"github-dark"}
git clone https://github.com/ellipse-software/bast
cd bast/apps/bast
go build -o ~/.local/bin/bast .
```

**2. Install the boxd CLI and sign in**

```bash theme={"theme":"github-dark"}
curl -fsSL https://boxd.sh/downloads/install.sh | sh
boxd auth login
```

Bast calls `boxd` from your `PATH` or `~/.local/bin`. Set `BOXD_CLI` to use a binary somewhere else.

**3. Sync your machines**

```bash theme={"theme":"github-dark"}
bast sync boxd
```

Or open `bast`, press `4` for Sync, select **boxd**, and choose **Sync now**. Your machines show up in the host list.

**4. Connect**

```bash theme={"theme":"github-dark"}
bast connect boxd_fra_web
```

Or pick the machine in the host list and press Enter.

## What gets synced

Bast syncs every region of the CLI's active organization (`boxd auth switch`). Set the org filter in the boxd submenu to sync a list of organizations instead.

Each machine becomes a host named `boxd_<region>_<name>`, grouped as `boxd/<org>/<region>`. The hosts live in `~/.ssh/bast/sync/boxd/config`. Stopped machines stay hidden until you press `.`.

The boxd CLI keeps a `Host` entry for each machine in `~/.ssh/config`. Bast copies its host name, port, user, and key, so a Bast host connects the same way as `ssh <name>.boxd`. SFTP in Bast's Files tab takes the same path.

## Connect to a sleeping or stopped machine

* **Standby or hibernated:** the SSH connection wakes the machine. Bast makes no extra call.
* **Stopped:** Enter starts the machine, syncs again, and then connects.

## Manage machines

| Action | TUI key | CLI |
| - | - | - |
| Create | `n` on the boxd group | `bast boxd new [--name web] [--org org] [--region fra] [--vcpu 2] [--snapshot name]` |
| Fork | `n` on a machine | `bast boxd fork <host> [--name name]` |
| Stop | `o` | `bast boxd stop <host>` |
| Start | `r` | `bast boxd start <host>` |
| Restart | `R` | `bast boxd restart <host>` |
| Delete | `d` | `bast boxd delete <host> [--yes]` |

`<host>` is the Bast host or the machine's name. `--vcpu` picks one of boxd's [machine sizes](https://docs.boxd.sh/guides/machine-specs.md): 1, 2, 4, or 8 vCPUs with 4 GiB each. Leave it out for your organization's default. A machine from a [snapshot](https://docs.boxd.sh/guides/snapshots.md) keeps the snapshot's size. A fork copies the disk, memory, and running processes, in the same region.

`bast boxd new` only creates machines in an organization Bast already syncs.

## Use an API key

Bast can sync and manage machines with an API key instead of a signed-in CLI:

```bash theme={"theme":"github-dark"}
boxd auth keys create bast --org <your-org>
export BOXD_TOKEN=bxd_...
```

The CLI writes SSH entries only for a signed-in session, so with a key alone `bast connect` doesn't work. Run `boxd auth login` to connect.

Bast's [boxd guide](https://bast.sh/docs/features/boxd) covers the rest, including the boxd submenu, auto-sync, and every key in the TUI.


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