# Bast.sh: full documentation

> Browse SSH hosts, manage keys, and connect from the terminal. The fast way into the servers you use every day.

Agent skill: npx skills add ellipse-software/bast -g -y (file: https://bast.sh/bast.skill.md)
Docs index: https://bast.sh/llms.txt

---

# Introduction (https://bast.sh/docs)


Bast is a terminal app for browsing SSH hosts, managing keys, transferring files, and connecting fast. Run `bast` and you get a full-screen interface with hosts, keys, Files, and optional cloud sync. Pick a server, press Enter, and Bast hands off to your system `ssh` binary.

No custom protocol and no hidden database. Bast reads the SSH configuration you already have, adds presentation metadata on top (groups, tags, favorites, notes), can import cloud VMs as read-only hosts, and keeps OpenSSH as the source of truth.

 {"name":"DemoScreenshot","children":"","attributes":{"src":"/intro.png","alt":"The Bast host picker with hosts and keys tabs","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":626,"end":630,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":626,"end":630,"loc":{"start":{"line":13,"column":9,"offset":626},"end":{"line":13,"column":13,"offset":630}},"value":1600,"raw":"1600","range":[626,630]},"start":626,"end":630,"loc":{"start":{"line":13,"column":9,"offset":626},"end":{"line":13,"column":13,"offset":630}},"range":[626,630]}],"sourceType":"module","comments":[],"loc":{"start":{"line":13,"column":9,"offset":626},"end":{"line":13,"column":13,"offset":630}},"range":[626,630]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"640","data":{"estree":{"type":"Program","start":642,"end":645,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":642,"end":645,"loc":{"start":{"line":14,"column":10,"offset":642},"end":{"line":14,"column":13,"offset":645}},"value":640,"raw":"640","range":[642,645]},"start":642,"end":645,"loc":{"start":{"line":14,"column":10,"offset":642},"end":{"line":14,"column":13,"offset":645}},"range":[642,645]}],"sourceType":"module","comments":[],"loc":{"start":{"line":14,"column":10,"offset":642},"end":{"line":14,"column":13,"offset":645}},"range":[642,645]}}}}} 

## What you can do [#what-you-can-do]

* Browse and search every host in your SSH config, including `Include` files
* Add, edit, favorite, and hide hosts with groups, tags, colors, and notes
* Sync hosts from [GCP](/docs/features/gcp), [AWS](/docs/features/aws), [Azure](/docs/features/azure), and [box.ascii.dev](/docs/features/box)
* Sync Bast-managed hosts and keys between machines with [Vault](/docs/features/vault) (end-to-end encrypted)
* Browse and transfer files over [SFTP](/docs/features/files) in a dual-pane Files tab
* Generate, import, export, and install SSH keys from the same interface
* Connect with one keypress, or jump straight in from the shell with `bast <label>`
* Use Bast from a phone or narrow terminal: the TUI switches to a [mobile layout](/docs/features/mobile-view) below 60 columns
* Automate everything through the CLI with optional JSON output

## Requirements [#requirements]

* macOS or Linux
* OpenSSH: `ssh`, `ssh-keygen`, `ssh-add`
* A Nerd Font is recommended for some glyphs, but Bast works without one

## Quick start [#quick-start]

Install Bast first: [Installation](/docs/install).

| Command                 | What it does                                      |
| ----------------------- | ------------------------------------------------- |
| `bast`                  | Open the host picker                              |
| `bast update`           | Update Bast when installed via the bast.sh script |
| `bast <label>`          | Connect directly to a host label                  |
| `bast "Production web"` | Labels with spaces work                           |
| `bast hosts list`       | List hosts without opening the TUI                |
| `bast keys list`        | List SSH keys without opening the TUI             |
| `bast sync gcp`         | Import GCP VMs into Bast                          |
| `bast sync aws`         | Import Amazon EC2 instances into Bast             |
| `bast sync azure`       | Import Azure Linux VMs into Bast                  |
| `bast sync box`         | Import box.ascii.dev hosts into Bast              |
| `bast vault login`      | Link this machine to encrypted Bast Vault         |

Press `?` inside the TUI for the full keyboard reference.

## AI agents [#ai-agents]

Using Bast with Cursor, Claude Code, or Codex? Install the [agent skill](/docs/reference/agents) with `npx skills add ellipse-software/bast -g -y`, or point your agent at [llms.txt](https://bast.sh/llms.txt).


---
Full docs index: https://bast.sh/llms.txt

---

# Installation (https://bast.sh/docs/install)


Three ways to get Bast on macOS or Linux.

## Installer script (recommended) [#installer-script-recommended]

Downloads the latest build for your architecture, verifies the SHA-256 checksum, and installs to `~/.local/bin` by default. Run the same command again to update. It skips the download when you are already on the latest version.

```bash
curl -fsSL https://bast.sh/install | sh
```

Set `BAST_INSTALL_DIR` to install somewhere else.

Make sure the install directory is on your `PATH`, then run `bast`.

## Homebrew [#homebrew]

```bash
brew install ellipse-software/tap/bast
```

## Nightly channel [#nightly-channel]

Nightly builds track the latest `master` commit and install to the same `bast` command as stable releases. Only one channel can be active at a time. Running either installer uninstalls the other channel first (including a Homebrew install of the other formula), then installs the requested channel.

```bash
curl -fsSL https://bast.sh/install-nightly | sh
```

Homebrew:

```bash
brew install ellipse-software/tap/bast-nightly
```

Run the same commands again to update. Use `bast update` for script installs on either channel.

## From source [#from-source]

Requires Go 1.26+:

```bash
git clone https://github.com/ellipse-software/bast.git
cd bast/apps/bast
go build -trimpath -o bast .
```

## Installer requirements [#installer-requirements]

The bast.sh script needs `curl`, `tar`, and `shasum` or `sha256sum`.

## After install [#after-install]

Run `bast` to open the host picker. Run `bast update` to update copies installed via the script (see [Updates](/docs/reference/updates)).


---
Full docs index: https://bast.sh/llms.txt

---

# AI agents (https://bast.sh/docs/reference/agents)


Bast ships resources for AI coding agents: an installable skill, machine-readable docs, and per-page shortcuts to open ChatGPT, Claude, or Cursor with context.

## Agent skill [#agent-skill]

The Bast skill teaches agents how to use the CLI correctly: `--json` automation, patch semantics for host edits, file paths, and safety rules (never paste private keys).

It uses the standard `SKILL.md` format and works in **Cursor**, **Claude Code**, **Codex**, and other agents supported by the [Skills CLI](https://skills.sh/).

The canonical skill lives in this repo at [`skills/bast/SKILL.md`](https://github.com/ellipse-software/bast/tree/master/skills/bast).

### Install with npx skills (recommended) [#install-with-npx-skills-recommended]

Global (user-level) install for every project:

```bash
npx skills add ellipse-software/bast -g -y
```

Project-local (commit agent skill dirs with your repo):

```bash
npx skills add ellipse-software/bast -y
```

List what the repo exposes without installing:

```bash
npx skills add ellipse-software/bast --list
```

Requires Node.js. The Skills CLI discovers `skills/bast/SKILL.md` and installs it into the agent directories you choose.

### Curl fallback (no Node) [#curl-fallback-no-node]

```bash
curl -fsSL https://bast.sh/install-skill | sh
```

This writes the skill to:

| Agent       | Path                             |
| ----------- | -------------------------------- |
| Cursor      | `~/.cursor/skills/bast/SKILL.md` |
| Claude Code | `~/.claude/skills/bast/SKILL.md` |
| Codex       | `~/.codex/skills/bast/SKILL.md`  |

Project-local via curl:

```bash
curl -fsSL https://bast.sh/install-skill | BAST_SKILL_SCOPE=project sh
```

Restart or start a new agent session after installing.

### One agent (manual) [#one-agent-manual]

```bash
# Cursor
mkdir -p ~/.cursor/skills/bast
curl -fsSL https://bast.sh/bast.skill.md -o ~/.cursor/skills/bast/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/bast
curl -fsSL https://bast.sh/bast.skill.md -o ~/.claude/skills/bast/SKILL.md

# Codex
mkdir -p ~/.codex/skills/bast
curl -fsSL https://bast.sh/bast.skill.md -o ~/.codex/skills/bast/SKILL.md
```

You can also [download the skill file](https://bast.sh/bast.skill.md) and copy it to the path above.

## llms.txt [#llmstxt]

Agents can fetch curated documentation without scraping the site:

| URL                                            | Purpose                             |
| ---------------------------------------------- | ----------------------------------- |
| [llms.txt](https://bast.sh/llms.txt)           | Index of all docs with descriptions |
| [llms-full.txt](https://bast.sh/llms-full.txt) | Full docs in one file               |

Each doc page also exposes processed Markdown (use **Copy Markdown** or **Open** on any docs page) for pasting into a chat or loading into context.

## Ask AI from the docs [#ask-ai-from-the-docs]

Every docs page includes **Copy Markdown** and an **Open** menu to start a conversation in ChatGPT, Claude, or Cursor with the current page URL as context.

On the [homepage](https://bast.sh), the footer has the same shortcuts plus the skill installer.

## What agents should know [#what-agents-should-know]

Brief version of what the skill covers, useful even without installing it:

* Bast wraps **OpenSSH**, not a custom SSH protocol. Connection settings live in `~/.ssh/config`; metadata (groups, tags, notes) lives in `~/.config/bast/state.json`.
* Use &#x2A;*`--json --no-input`*&#x2A; for scripts. Add &#x2A;*`--yes`** for deletes and exports.
* Host and key edits are **patches**: only flags you pass change. Use `--clear-*` flags to remove values.
* Prefer `bast hosts` / `bast keys` subcommands over the TUI in non-interactive environments.

See [Command line](/docs/features/cli) and [Files and storage](/docs/reference/files) for the full reference.


---
Full docs index: https://bast.sh/llms.txt

---

# Files and storage (https://bast.sh/docs/reference/files)


Bast keeps things in predictable places on your machine. Cloud sync only writes local SSH config from provider APIs. Vault stores an encrypted backup of Bast-managed state remotely, never plaintext.

## Managed SSH config [#managed-ssh-config]

```
~/.ssh/bast/config
```

Host blocks you create through Bast are written here. Your main `~/.ssh/config` gets one `Include` line pointing at this file. External hosts can be copied here with [promote](/docs/features/vault#promote).

## GCP sync config [#gcp-sync-config]

```
~/.ssh/bast/sync/gcp/config
```

Hosts imported from GCP are written here. Bast includes this file from `~/.ssh/bast/config` while GCP sync is enabled. Disconnecting removes the Include and the generated file. See [GCP](/docs/features/gcp).

## AWS sync config [#aws-sync-config]

```
~/.ssh/bast/sync/aws/config
```

Amazon EC2 hosts imported through AWS sync are written here. Bast includes this file from `~/.ssh/bast/config` while AWS sync is enabled. Disconnecting removes the Include and the generated file. See [AWS](/docs/features/aws).

## Azure sync config [#azure-sync-config]

```
~/.ssh/bast/sync/azure/config
```

Azure Linux VMs imported through Azure sync are written here. Bast includes this file from `~/.ssh/bast/config` while Azure sync is enabled. Disconnecting removes the Include and the generated file. See [Azure](/docs/features/azure).

## Box sync config [#box-sync-config]

```
~/.ssh/bast/sync/box/config
```

ASCII Box sandboxes imported through box.ascii.dev sync are written here. Bast includes this file from `~/.ssh/bast/config` while Box sync is enabled. Disconnecting removes the Include and the generated file. See [box.ascii.dev](/docs/features/box).

## Managed keys [#managed-keys]

```
~/.ssh/bast/keys/
```

Generated, imported, and promoted keys live here. Private keys are written at mode `0600`. Sync also checks keys under `~/.ssh`.

GCP falls back to `~/.ssh/google_compute_engine` when no local key matches VM metadata or an OS Login profile. AWS checks for a private key matching the EC2 key-pair name, then falls back to `~/.ssh/bast/aws_compute` through EC2 Instance Connect. Box uses `~/.ssh/ascii_box_ed25519`.

Azure checks deployment public keys against local keys. Microsoft Entra key and certificate material generated by Azure CLI is stored under:

```
~/.ssh/bast/azure/
```

## Metadata [#metadata]

```
~/.config/bast/state.json
```

Stores presentation metadata, cloud sync settings, pending history suggestions, and per-file history scan checkpoints. Bast does not store the original shell history commands.

## Vault session [#vault-session]

```
~/.config/bast/vault-session.json
~/.config/bast/vault-passphrase
```

Device bearer token and vault revision live in `vault-session.json`. The local encryption passphrase is stored in `vault-passphrase` (mode `0600`) so Bast can unlock without prompting every launch. Treat that file like an unlocked private key on disk: anyone who can read it can decrypt your vault ciphertext. Log out clears both. The passphrase is never sent to Bast servers.

## What stays in OpenSSH [#what-stays-in-openssh]

Connection settings (hostname, user, port, identity and certificate files, proxy jump, and cloud tunnel ProxyCommands) live in SSH config files. Bast does not duplicate them in its metadata store.

## Backups [#backups]

Back up `~/.ssh` before testing unreleased builds against a production config. Never paste real private keys into issues or bug reports.


---
Full docs index: https://bast.sh/llms.txt

---

# Self-hosting (https://bast.sh/docs/reference/self-hosting)


Self-host the Bast web app when you want Vault ciphertext, OTP sessions, and related API routes on your own infrastructure. The CLI and TUI keep encrypting locally; your server only stores opaque blobs and email codes.

Hosted [bast.sh](https://bast.sh) remains the default. Point Bast at your origin when you self-host.

## What you are hosting [#what-you-are-hosting]

The app in `apps/web` serves:

* The marketing site and docs
* Installer scripts under `/install` and `/install-nightly`
* Vault APIs: `/api/auth/otp/*`, `/api/auth/logout`, `/api/vault`
* Optional telemetry and error ingest (`/api/telemetry`, `/api/errors`)

Vault needs three backends:

| Role                          | Service                                                                                    | Env vars                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| Sessions, OTP, vault metadata | [Upstash Redis](https://upstash.com/) (Redis REST)                                         | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN`                                                         |
| Ciphertext blobs              | [Cloudflare R2](https://developers.cloudflare.com/r2/)                                     | `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`                                |
| Login emails                  | [Cloudflare Email Sending](https://developers.cloudflare.com/email-routing/email-sending/) | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` (or reuse `R2_ACCOUNT_ID`), optional `CLOUDFLARE_EMAIL_FROM` |

Copy `apps/web/.env.example` and fill in values. Telemetry (`POSTHOG_*`) and error reporting (`SENTRY_DSN`) are optional; leave them empty to disable forwarding.

In local development without email credentials, OTP codes are printed to the server log instead of being emailed. Production requires email configuration.

## Run it [#run-it]

Requires Bun 1.3+ (see the repository root `packageManager`).

```bash
git clone https://github.com/ellipse-software/bast.git
cd bast
bun install
cp apps/web/.env.example apps/web/.env.local
# edit apps/web/.env.local
bun run build:web
bun run --cwd apps/web start
```

`next start` listens on port 3000 by default. Put TLS termination and a stable hostname in front of it (Caddy, nginx, a reverse proxy, or your platform).

You can also deploy `apps/web` on [Vercel](https://vercel.com/) or any Node host that can run Next.js. Set the project root to `apps/web` (lockfile stays at the monorepo root). Configure the same environment variables in the host.

Enable Cloudflare Email Sending for the domain you put in `CLOUDFLARE_EMAIL_FROM` before expecting production OTP delivery.

## Point Bast at your server [#point-bast-at-your-server]

Each machine stores the vault API base in `~/.config/bast/vault-session.json` (`apiBase`).

**TUI:** Sync → Vault → **API base URL**, or set it on the link form. Then **Link account**.

**CLI:**

```bash
bast vault login --email you@example.com --api https://vault.example.com
bast vault status
```

**Environment override** (wins over the saved session for requests):

```bash
export BAST_VAULT_API=https://vault.example.com
```

Use the same origin on every machine that should share a vault. Switching servers for an already-linked machine: log out, set the new API base, then link again. Ciphertext does not move automatically between servers.

## Security notes [#security-notes]

* The passphrase never leaves the Bast client. The server sees ciphertext only.
* Protect Redis and R2 credentials; they can read or delete vault blobs for accounts on that deployment.
* Serve the app over HTTPS in production.
* OTP email is the account recovery surface: lock down who can send as your From address.

See [Vault](/docs/features/vault) for what syncs and how encryption works.


---
Full docs index: https://bast.sh/llms.txt

---

# Telemetry (https://bast.sh/docs/reference/telemetry)


Bast sends optional anonymous telemetry to help improve the tool. This includes version, platform, and usage events (for example TUI open, SSH connect, cloud sync, files connect/shell, and vault link/sync). No hostnames, keys, project IDs, emails, or SSH config contents are collected by default.

When an error occurs in an interactive session, Bast may offer to send an anonymous error report. Press Space to send, or any other key to continue without sending. Error reports can include the error message shown on screen (which may contain paths or labels). SSH session endings are never reported.

The bast.sh website and installer use the same policy. Usage events go to `/api/telemetry`. Consented error reports go to `/api/errors`.

## Opt out [#opt-out]

Set this environment variable before running Bast:

```bash
export BAST_NO_TELEMETRY=1
```

This disables usage telemetry and error reporting. Add it to your shell profile to make it permanent.


---
Full docs index: https://bast.sh/llms.txt

---

# Updates (https://bast.sh/docs/reference/updates)


Tagged builds check GitHub for a newer stable release in the background when you launch Bast. If one exists, a reminder appears in the footer without slowing startup. Network failures are ignored quietly.

## Update suggestions [#update-suggestions]

The reminder depends on how you installed Bast:

| Install method         | Suggested action            |
| ---------------------- | --------------------------- |
| bast.sh script         | `bast update`               |
| bast.sh nightly script | `bast update`               |
| Homebrew               | `brew upgrade bast`         |
| Homebrew nightly       | `brew upgrade bast-nightly` |
| Source build           | Link back to bast.sh        |

Press `v` in the TUI to see version info and the update suggestion.

## bast update [#bast-update]

```bash
bast update
```

This only runs when the bast.sh installer receipt is present beside the executable. It works for both stable and nightly script installs, and will not overwrite Homebrew-managed or source-built copies.

The script downloads the latest release, verifies the checksum, and replaces the binary in place.

## Check manually [#check-manually]

Visit [github.com/ellipse-software/bast/releases](https://github.com/ellipse-software/bast/releases) for release notes and download links.


---
Full docs index: https://bast.sh/llms.txt

---

# Advanced host options (https://bast.sh/docs/features/advanced-host-options)


Advanced host options control how OpenSSH starts and carries a connection. Open the host form, choose **Advanced**, then choose a section. Blank or **Default** values leave the decision to OpenSSH and your wider SSH config.

## Jump and proxy [#jump-and-proxy]

| Option     | What it does                                                                                                                           | Example   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Proxy jump | Connects through another SSH host before reaching the destination. Choose a host already known to Bast or enter an SSH alias manually. | `bastion` |

This writes OpenSSH's `ProxyJump` setting. The jump value should be an SSH host alias, not a display label containing spaces.

## Session [#session]

| Option          | What it does                                                                                                                                             | Example               |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Startup command | Runs a command on the server immediately after connecting.                                                                                               | `tmux attach -t main` |
| Request TTY     | Controls whether SSH allocates a terminal. **Force yes** is useful for interactive startup commands; **Disable** is useful for non-interactive commands. | `Force yes`           |

Startup command maps to `RemoteCommand`. Request TTY maps to `RequestTTY force` or `RequestTTY no`.

## Forwarding [#forwarding]

| Option           | What it does                                                                                                                                           | Example               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| Agent forwarding | Lets the remote server use keys from your local ssh-agent. Only enable it for servers you trust.                                                       | `Yes`                 |
| Local forwards   | Makes a service reachable on a local port. Use `local-port destination-host:destination-port`. Separate multiple forwards with semicolons.             | `8080 localhost:80`   |
| Remote forwards  | Makes a local service reachable from the remote side. Use `remote-port destination-host:destination-port`. Separate multiple forwards with semicolons. | `9000 localhost:3000` |
| Dynamic forward  | Starts a local SOCKS proxy on the given port.                                                                                                          | `1080`                |
| Compression      | Enables SSH compression. It can help on slow links but usually adds overhead on fast networks.                                                         | `Yes`                 |
| Keepalive        | Sends a server-alive message after this many idle seconds. This can keep connections alive through firewalls and NAT.                                  | `30`                  |

These values map to `ForwardAgent`, `LocalForward`, `RemoteForward`, `DynamicForward`, `Compression`, and `ServerAliveInterval`.

Agent forwarding gives the remote host access to your agent while the session is open. It does not copy private-key files to the server, but a compromised server could use the forwarded agent during that session.

## Environment [#environment]

Environment variables use `NAME=value` pairs and OpenSSH's `SetEnv` setting. Separate multiple values with semicolons:

```text
APP_ENV=production; LOG_LEVEL=info
```

The SSH server can restrict which environment variables it accepts.

## Custom flags [#custom-flags]

Use custom flags for OpenSSH options that do not have a dedicated field. Enter one directive and value per item, separated by semicolons:

```text
TCPKeepAlive yes; ConnectTimeout 10
```

Bast rejects directives that would redefine the host block or bypass dedicated fields. Avoid duplicating an option already available elsewhere in the form.

## CLI equivalents [#cli-equivalents]

Every advanced field has a matching option on `bast hosts add` and `bast hosts edit`:

| TUI option           | Set with                  | Remove or reset with      |
| -------------------- | ------------------------- | ------------------------- |
| Proxy jump           | `--proxy-jump`            | `--clear-proxy-jump`      |
| Agent forwarding     | `--forward-agent yes\|no` | `--clear-forward-agent`   |
| Startup command      | `--startup-command`       | `--clear-startup-command` |
| Request TTY          | `--request-tty force\|no` | `--clear-request-tty`     |
| Environment variable | `--set-env`               | `--clear-set-env`         |
| Local forward        | `--local-forward`         | `--clear-local-forward`   |
| Remote forward       | `--remote-forward`        | `--clear-remote-forward`  |
| Dynamic forward      | `--dynamic-forward`       | `--clear-dynamic-forward` |
| Compression          | `--compression yes\|no`   | `--clear-compression`     |
| Keepalive            | `--keepalive`             | `--clear-keepalive`       |
| Custom flag          | `--ssh-option`            | `--clear-ssh-options`     |

Repeat `--set-env`, `--local-forward`, `--remote-forward`, or `--ssh-option` to add more than one value.

```bash
bast hosts add "Production web" \
  --hostname prod.example.com \
  --proxy-jump bastion \
  --startup-command "tmux attach -t main" \
  --request-tty force \
  --set-env APP_ENV=production \
  --local-forward "8080 localhost:80" \
  --keepalive 30
```

Host edits are patches, so omitted options stay unchanged. Use the matching clear option to restore the OpenSSH default or remove existing values, for example:

```bash
bast hosts edit Production_web \
  --clear-proxy-jump \
  --clear-startup-command \
  --clear-local-forward
```

Run `bast hosts add --help` or `bast hosts edit --help` for the option list.


---
Full docs index: https://bast.sh/llms.txt

---

# Connections (https://bast.sh/docs/features/connections)


Select a host and press Enter to connect. On [narrow terminals](/docs/features/mobile-view), click or tap the **Connect** button in the detail panel instead.

Bast clears the terminal, shows a short connection banner, launches `ssh` with that host's config, and returns you to the picker when the session ends.

## Connection banner [#connection-banner]

Before `ssh` starts, Bast prints:

```
 BAST   Connecting to server…
 Stuck? Press Enter, then ~. to return to Bast.
```

The same banner appears for TUI connects and direct shell connects (`bast <label>` / `bast connect`).

For cloud-synced hosts, Bast may print muted progress lines under the banner while it prepares access. This includes GCP key registration, AWS EC2 Instance Connect, Azure Microsoft Entra certificate requests, and Box SSH key authorization. See the [GCP](/docs/features/gcp), [AWS](/docs/features/aws), [Azure](/docs/features/azure), and [box.ascii.dev](/docs/features/box) pages for exact behavior.

## Direct connect from the shell [#direct-connect-from-the-shell]

You can skip the TUI entirely:

```bash
bast production_web
bast "Production web"
bast connect production_web
```

Labels with spaces work when quoted. Bast resolves them to the correct SSH alias under the hood. Cloud hosts get the same banner and access-preparation steps as in the TUI.

## Native OpenSSH [#native-openssh]

Bast always launches your system's `ssh` binary. There is no proprietary runtime or custom transport. Whatever works in your terminal with plain `ssh` will work through Bast.

For browsing and transferring files without a full shell session, use the [Files](/docs/features/files) tab (OpenSSH SFTP over the same host config).

## During a session [#during-a-session]

Typing `exit` ends the SSH session and returns to the picker. From the picker, press `q` to exit Bast.

If a session gets stuck, press Enter then `~.` to force-close SSH and land back in the picker. That is the standard OpenSSH escape sequence.

## Connection tracking [#connection-tracking]

Each successful connection updates last-used time and connection count in Bast metadata. That feeds into smart sort so your frequent servers stay at the top.


---
Full docs index: https://bast.sh/llms.txt

---

# Files (https://bast.sh/docs/features/files)


The Files tab is a dual-pane browser. Each pane can be **local** or **remote**, in any combination (local↔local, local↔remote, remote↔remote). Press `4`, or `F` on a host from Hosts to open Files and connect that host on the right pane.

## Pane modes [#pane-modes]

| Tone                | Meaning                   |
| ------------------- | ------------------------- |
| Slate label `local` | Local filesystem          |
| Amber `remote`      | Disconnected: pick a host |
| Teal host alias     | Connected over SFTP       |

| Key       | Action                                                   |
| --------- | -------------------------------------------------------- |
| `L` / `R` | Make the focused pane local / remote                     |
| `w`       | Swap left and right panes                                |
| `h` / `l` | Parent / enter directory                                 |
| `g` / `G` | Top / bottom of list                                     |
| `/`       | Edit path (or search hosts on a picker)                  |
| `f`       | Fuzzy jump (type to filter, then a label letter to land) |
| `D`       | Disconnect a connected remote pane                       |

## Connecting [#connecting]

In a remote pane, select a host and press Enter. Bast prepares cloud access the same way as a normal [connection](/docs/features/connections), then opens OpenSSH SFTP (`ssh -s sftp`).

SFTP uses `BatchMode`, so passphrase and host-key prompts cannot interrupt the TUI. If connect fails, unlock the key with `ssh-add`, or Connect once from Hosts to accept the host key, then retry.

## Navigation [#navigation]

| Key                    | Action                                    |
| ---------------------- | ----------------------------------------- |
| `↑` / `↓` or `j` / `k` | Move                                      |
| `Enter`                | Enter directory, or connect selected host |
| `h` / `Backspace`      | Parent directory                          |
| `Tab`                  | Switch pane                               |
| `/`                    | Jump to a typed path (or search hosts)    |
| `.`                    | Toggle hidden files                       |
| `␣`                    | Toggle mark                               |
| `v`                    | Start or finish a range mark              |
| `f`                    | Fuzzy jump                                |

Click a pane to focus it, a row to select it, and the same row again to enter a directory or connect a host. Click the path header to edit the path (or search hosts on a picker). Scroll wheel moves the pane under the pointer.

### Fuzzy jump [#fuzzy-jump]

Press `f` on a file list. Entries go muted until you type. Matches light up and get a letter label (`a`, `s`, `d`, …). Keep typing to narrow, or type a label letter to jump there (flash-style). `Esc` cancels.

Copy and move always target the **other** pane’s current directory.

## Transfers and edits [#transfers-and-edits]

| Key         | Action                                                       |
| ----------- | ------------------------------------------------------------ |
| `c`         | Copy marked items (or the cursor row) to the other pane      |
| `m`         | Move (copy, then delete source)                              |
| `d`         | Delete (confirm by typing the name, or `DELETE` for a batch) |
| `a`         | Create directory                                             |
| `r`         | Rename                                                       |
| `i`         | File info (name, type, size, mode)                           |
| `p`         | Change permissions (chmod) on local or remote items          |
| `esc` / `x` | Cancel an in-progress transfer                               |

### File info [#file-info]

Press `i` on the cursor row. The focused pane shows name, type, size, mode (octal and symbolic), and modified time. `j`/`k` move to the next or previous item while info stays open. `p` jumps into the permissions editor. `i` or `Esc` closes.

### Permissions [#permissions]

Press `p` on the cursor row or marked items. The focused pane opens an inline permissions grid for Owner / Group / Other with Read / Write / Exec. The current mode seeds the checkboxes.

| Key                                | Action                                                        |
| ---------------------------------- | ------------------------------------------------------------- |
| `←` `→` `↑` `↓` or `h` `j` `k` `l` | Move across the grid                                          |
| `Space` or `x`                     | Toggle the focused bit (or recursive / octal focus)           |
| `0`-`7`                            | Set the current class (owner/group/other) to that octal digit |
| `u` `g` `o`                        | Jump to Owner / Group / Other                                 |
| `/`                                | Edit the octal mode directly                                  |
| `Enter`                            | Apply                                                         |
| `Esc`                              | Cancel                                                        |

When any selected path is a directory, a **contents** option appears. Turn it on to apply the mode recursively (symlinks are skipped while walking).

Works the same on local and remote panes. The other pane stays visible while you edit.

## Open a shell here [#open-a-shell-here]

Press `t` on a local pane for `$SHELL` in that directory, or on a connected remote pane for `ssh` with cwd set (host `RemoteCommand` is cleared for this jump). On a host picker, `t` opens a normal SSH session for the selected host.

## What this is not (yet) [#what-this-is-not-yet]

Deferred for later:

* Fuzzy find across the whole tree (current `f` jump is per-pane listing)
* Directory sync / mirror
* Trash / undo
* chown UI
* Inline previews
* Shared ControlMaster connections

## Native OpenSSH [#native-openssh]

Transfers use your system `ssh` binary and the same SSH config as Connect, including ProxyJump and cloud ProxyCommand tunnels.


---
Full docs index: https://bast.sh/llms.txt

---

# Import from shell history (https://bast.sh/docs/features/history-import)


Bast scans supported shell history files in the background when it starts. SSH destinations that are not already configured appear in a muted, collapsible &#x2A;*(Suggested)** group below your hosts.

## Review suggestions [#review-suggestions]

| Key     | Action                                 |
| ------- | -------------------------------------- |
| `Enter` | Add the selected suggestion            |
| `e`     | Review and edit it before adding       |
| `x`     | Dismiss it                             |
| `Space` | Collapse or expand the Suggested group |

Search includes suggestions and temporarily expands the group when necessary.

Bast can recover the destination, username, port, identity file, and ProxyJump from common `ssh` commands. Review mode uses the normal host form, so you can change the label, group, authentication, or advanced SSH options before saving.

## Supported history files [#supported-history-files]

| Shell | Files                                                                                           |
| ----- | ----------------------------------------------------------------------------------------------- |
| zsh   | `~/.zsh_history`, `~/.zhistory`, `$HISTFILE`, `$ZDOTDIR/.zsh_history`, and `$ZDOTDIR/.zhistory` |
| bash  | `~/.bash_history` and `$HISTFILE`                                                               |
| fish  | `$XDG_DATA_HOME/fish/${fish_history}_history`, defaulting to `~/.local/share/fish/fish_history` |

Environment-defined paths are used when those variables are available to the Bast process. The standard zsh paths include `~/.zhistory` because `HISTFILE` is often assigned without being exported.

## Rescanning and privacy [#rescanning-and-privacy]

The first scan reads each available history file in the background. Later starts use per-file checkpoints, including recovery for rotated or rewritten files, rather than replaying old entries. Accepted and dismissed entries are removed from the suggestion list. The same destination can be suggested again if a new SSH command for it is recorded later.

Bast never executes history commands. It stores the normalized connection fields needed for pending suggestions and the scan checkpoints, not the original command text.


---
Full docs index: https://bast.sh/llms.txt

---

# Host management (https://bast.sh/docs/features/host-management)


Press `a` to add a host or `e` to edit the selected one. The form keeps the required label and hostname at the top, with separate menus for authentication, advanced SSH settings, and metadata. Click **Save** or press `Ctrl+J` to save from anywhere in the form. `Ctrl+Enter` remains available when your terminal reports it.

## Connection fields [#connection-fields]

| Field    | Purpose                                                         |
| -------- | --------------------------------------------------------------- |
| Label    | Display name shown in the list (spaces become SSH-safe aliases) |
| Hostname | Server hostname or IP address                                   |
| User     | Remote username (blank uses your SSH default)                   |
| Port     | Port number (blank defaults to 22)                              |
| Identity | Key file, password auth, or ssh-agent defaults                  |

Choose **Advanced** to configure jump hosts, startup commands, forwarding, keepalives, environment variables, and custom OpenSSH flags. See [Advanced host options](/docs/features/advanced-host-options) for each setting and its CLI equivalent.

## Metadata fields [#metadata-fields]

**Groups** use slash paths like `Work/Production`. You can nest up to five levels. Press `m` on a local host, then type to fuzzy-search existing groups. Choose a match, select the create row for a new path, or clear the group with **No group**. Press Space on a group header to collapse or expand it.

**Tags** are comma-separated labels included in search.

**Environment** is a free-form field (for example `production` or `staging`).

**Color** tints the label in the list so you can spot servers at a glance. Use a hex value.

**Notes** are short text included in the detail panel and search results.

## Actions [#actions]

| Key | Action                                         |
| --- | ---------------------------------------------- |
| `f` | Favorite the selected host                     |
| `m` | Move the selected local host to a group        |
| `h` | Hide a host you rarely need                    |
| `.` | Toggle whether hidden hosts appear in the list |
| `d` | Delete a Bast-managed host                     |
| `K` | Remove a host from your known-hosts file       |

Favoriting and hiding are presentation-only changes stored in Bast metadata. Deleting removes the host block from Bast's managed config.

Removing a known-host entry (`K`) helps when a server fingerprint changes and SSH refuses to connect.

## External hosts [#external-hosts]

Hosts defined outside Bast's managed config can still be edited for metadata (group, tags, notes, and so on). Bast will not change their connection settings or delete them.

## Synced hosts [#synced-hosts]

Hosts imported from [GCP](/docs/features/gcp), [AWS](/docs/features/aws), [Azure](/docs/features/azure), or [box.ascii.dev](/docs/features/box) are read-only for connection settings and grouping. GCP, AWS, and Azure hosts can still be favorited or hidden; Box hosts are fully sync-owned. Disconnect the provider in the Sync tab to remove them. Bast prepares provider-specific SSH access immediately before connecting.


---
Full docs index: https://bast.sh/llms.txt

---

# Host picker (https://bast.sh/docs/features/host-picker)


The host list shows every entry Bast discovers in your SSH config, including hosts pulled in through `Include` files. Each row shows a label, destination, and any metadata you have set.

SSH destinations found in supported shell history files appear below configured hosts in a collapsible &#x2A;*(Suggested)** group. See [Import from shell history](/docs/features/history-import).

 {"name":"DemoScreenshot","children":"","attributes":{"src":"/hosts.png","alt":"Searching and sorting the host list","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":471,"end":475,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":471,"end":475,"loc":{"start":{"line":13,"column":9,"offset":471},"end":{"line":13,"column":13,"offset":475}},"value":1600,"raw":"1600","range":[471,475]},"start":471,"end":475,"loc":{"start":{"line":13,"column":9,"offset":471},"end":{"line":13,"column":13,"offset":475}},"range":[471,475]}],"sourceType":"module","comments":[],"loc":{"start":{"line":13,"column":9,"offset":471},"end":{"line":13,"column":13,"offset":475}},"range":[471,475]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"500","data":{"estree":{"type":"Program","start":487,"end":490,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":487,"end":490,"loc":{"start":{"line":14,"column":10,"offset":487},"end":{"line":14,"column":13,"offset":490}},"value":500,"raw":"500","range":[487,490]},"start":487,"end":490,"loc":{"start":{"line":14,"column":10,"offset":487},"end":{"line":14,"column":13,"offset":490}},"range":[487,490]}],"sourceType":"module","comments":[],"loc":{"start":{"line":14,"column":10,"offset":487},"end":{"line":14,"column":13,"offset":490}},"range":[487,490]}}}}} 

## Search [#search]

Press `/` to search across labels, hostnames, groups, tags, environments, and notes. The list filters as you type.

## Sort modes [#sort-modes]

Press `s` to cycle through sort modes:

* **Smart** (default): favorites and recently used hosts float to the top
* **Label**: alphabetical by display name
* **Recent**: ordered by last connection time
* **Group**: grouped by folder path, then smart order within each group

Bast tracks when you last connected and how often, so servers you use every day stay easy to reach.

## Reload [#reload]

Press `r` any time to reload your config from disk. That is useful when you edit `~/.ssh/config` in another editor while Bast is open.

## Host details [#host-details]

Select a host to see the detail panel on the right: hostname, user, port, identity files, authentication mode, proxy jump, group, tags, environment, notes, and connection history.

On terminals narrower than 60 columns, Bast stacks the list above the details instead. See [Mobile layout](/docs/features/mobile-view) for connect buttons, touch input, and how the layout adapts.


---
Full docs index: https://bast.sh/llms.txt

---

# SSH config (https://bast.sh/docs/features/ssh-config)


Bast treats your SSH config as the source of truth. It does not replace OpenSSH or maintain a separate host database.

## First run [#first-run]

On first use, Bast prepends a single line to your main SSH config:

```
Include ~/.ssh/bast/config
```

New hosts you create through Bast are written to that managed file. Everything else stays where it already lives.

## Discovery [#discovery]

Bast discovers hosts from your main config and every file it includes. Externally managed blocks keep their original source path. Bast-managed blocks are marked so you know which ones it owns.

## Labels and aliases [#labels-and-aliases]

Display labels with spaces (like "Production web") map to safe OpenSSH alias names automatically. You can connect with either the label or the alias from the shell:

```bash
bast "Production web"
bast Production_web
```

## What Bast stores separately [#what-bast-stores-separately]

Presentation metadata (groups, tags, colors, notes, favorites, recency) lives in `~/.config/bast/state.json`. Connection settings live in SSH config files where they belong.

Back up `~/.ssh` before testing unreleased builds against a production config.


---
Full docs index: https://bast.sh/llms.txt

---

# Key selector (https://bast.sh/docs/features/key-selector)


When you add or edit a host, the identity field is a picker, not just a text box. Bast offers detected keys, `ssh-agent` defaults, password-only auth, and a custom path if you need something else.

## Options [#options]

* **Detected keys**: every key Bast knows about, with name and fingerprint
* **Agent defaults**: let OpenSSH try keys from `ssh-agent` in its usual order
* **Password only**: disable public-key auth for hosts that require a password
* **Custom path**: point at any identity file on disk

This keeps host setup practical. Pick the key you mean instead of remembering file paths, or switch a host to password auth without hand-editing config syntax.

The same picker appears when editing an existing host, so you can change identity files without touching `~/.ssh/config` by hand.


---
Full docs index: https://bast.sh/llms.txt

---

# Key management (https://bast.sh/docs/features/keys)


Switch to the keys tab with `2`. Bast lists keys it finds on disk, keys in `ssh-agent`, and which hosts reference each key.

 {"name":"DemoScreenshot","children":"","attributes":{"src":"/keys.png","alt":"The keys tab with generate, import, and export actions","width":{"type":"mdxJsxAttributeValueExpression","value":"1600","data":{"estree":{"type":"Program","start":236,"end":240,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":236,"end":240,"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"value":1600,"raw":"1600","range":[236,240]},"start":236,"end":240,"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"range":[236,240]}],"sourceType":"module","comments":[],"loc":{"start":{"line":11,"column":9,"offset":236},"end":{"line":11,"column":13,"offset":240}},"range":[236,240]}}},"height":{"type":"mdxJsxAttributeValueExpression","value":"500","data":{"estree":{"type":"Program","start":252,"end":255,"body":[{"type":"ExpressionStatement","expression":{"type":"Literal","start":252,"end":255,"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"value":500,"raw":"500","range":[252,255]},"start":252,"end":255,"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"range":[252,255]}],"sourceType":"module","comments":[],"loc":{"start":{"line":12,"column":10,"offset":252},"end":{"line":12,"column":13,"offset":255}},"range":[252,255]}}}}} 

## Actions [#actions]

| Key | Action                                                                                |
| --- | ------------------------------------------------------------------------------------- |
| `a` | Generate a new ed25519 or RSA keypair                                                 |
| `i` | Import an existing private key from a file or pasted PEM                              |
| `e` | Edit the comment on a public key                                                      |
| `u` | Push a public key to a remote `~/.ssh/authorized_keys`                                |
| `x` | Export key files to a folder you choose                                               |
| `p` | Promote an external key into Bast-managed storage, or change a managed key passphrase |
| `c` | Copy the public key to your clipboard                                                 |
| `d` | Delete a Bast-managed keypair                                                         |

## Generate [#generate]

Create a new key in Bast's managed keys directory (`~/.ssh/bast/keys`). Choose ed25519 or RSA and optionally set a passphrase.

## Import [#import]

Bring in an existing private key from a file path or pasted PEM text. Bast can derive the public key if you do not provide one. It verifies keypairs on import so mismatched public and private keys are caught early.

Import from stdin without putting key material in shell history:

```bash
bast keys import work --private - < id_ed25519
```

## Promote [#promote]

Copy an external key from `~/.ssh` into Bast-managed keys so it can participate in [Vault](/docs/features/vault):

```bash
bast keys promote id_ed25519 --name work
```

## Add to server [#add-to-server]

Push a public key to a remote server's `authorized_keys`. Bast may prompt for a password if the server requires it. This uses your system `ssh` to copy the key.

## Export [#export]

Copy key files to a directory you choose. You confirm by typing `EXPORT` because private keys are sensitive. Pass `--yes` on the CLI to skip the confirmation in scripts.

## Storage [#storage]

Generated and imported keys live in `~/.ssh/bast/keys`. Private keys are written at mode `0600`. Never paste real private keys into issues or bug reports.


---
Full docs index: https://bast.sh/llms.txt

---

# Command line (https://bast.sh/docs/features/cli)


Everything in the TUI is also available from the shell. That matters for scripts, automation, and tools that need stable output.

## Host commands [#host-commands]

```bash
bast hosts list --sort group
bast hosts show production_web
bast hosts add "Production web" --hostname prod.example.com --user deploy --group Work/Production --tag web
bast hosts edit production_web --notes "Primary application server"
bast hosts favorite production_web
bast hosts hide old_server
bast hosts known-host remove production_web
bast hosts delete production_web
```

Host edits are patches: fields you omit stay unchanged. Flags like `--clear-group`, `--clear-notes`, and `--clear-identity` remove values on purpose.

Advanced connection settings use dedicated flags:

```bash
bast hosts add "Production web" --hostname prod.example.com \
  --proxy-jump bastion \
  --forward-agent no \
  --startup-command "tmux attach -t main" \
  --request-tty force \
  --set-env APP_ENV=production \
  --local-forward "8080 localhost:80" \
  --keepalive 30
```

Repeat `--set-env`, `--local-forward`, `--remote-forward`, and `--ssh-option` for multiple values. On edit, use the matching `--clear-*` flag to remove a value or return to the OpenSSH default.

See [Advanced host options](/docs/features/advanced-host-options) for what every option does, syntax examples, and security notes.

Run `bast hosts <command> --help` for the full option list per command.

## Key commands [#key-commands]

```bash
bast keys list
bast keys generate work --algorithm ed25519
bast keys import work --private ~/.ssh/id_ed25519
bast keys comment work --comment "Work laptop"
bast keys public work
bast keys install work --host production_web
bast keys export work --directory ~/Desktop --yes
bast keys delete work --yes
```

Run `bast keys <command> --help` for command-specific usage.

## Sync commands [#sync-commands]

```bash
bast sync gcp
bast sync aws
bast sync azure
bast sync box
bast sync status
bast sync disable gcp
bast sync disable box
```

Sync imports cloud hosts as read-only. Cloud connections through `bast connect` or `bast <label>` use the same banner and access-preparation flow as the TUI. See [GCP](/docs/features/gcp), [AWS](/docs/features/aws), [Azure](/docs/features/azure), or [box.ascii.dev](/docs/features/box) for provider setup.

## JSON mode [#json-mode]

Pass `--json` anywhere in the command for machine-readable output. It disables prompts, so pair it with flags like `--yes` for destructive actions:

```bash
bast hosts list --json
bast --json hosts show production_web
bast keys generate automation --no-passphrase --json
```

Success looks like `{"ok":true,"data":...}`. Errors go to stderr with a non-zero exit code. Commands that need an interactive SSH session or passphrase entry reject `--json` with `interactive_required`.

## Prompts and confirmations [#prompts-and-confirmations]

Commands prompt for missing input and sensitive confirmations when attached to a terminal. Pass `--yes` to explicitly approve deletion, known-host removal, or private-key export in unattended use. Pass `--no-input` to never prompt (fields must be provided via flags).


---
Full docs index: https://bast.sh/llms.txt

---

# Mobile layout (https://bast.sh/docs/features/mobile-view)


When your terminal is narrower than 60 columns, Bast switches to a mobile layout. The host and key lists stack above the detail panel instead of sitting side by side, so everything stays readable on a phone SSH app or a resized terminal window.

## Layout [#layout]

In mobile layout:

* The list takes the top half of the screen and scrolls independently
* A horizontal rule separates the list from the details below
* Detail fields use the full terminal width

Resize back above 60 columns and Bast returns to the usual two-column layout automatically.

## Connecting on narrow screens [#connecting-on-narrow-screens]

On the hosts tab, the detail panel shows a highlighted **Connect** button. Click or tap it to start a session, the same action as pressing Enter in the desktop layout.

The footer hint updates to remind you: `click Connect` alongside the usual navigation keys.

## Mouse and touch [#mouse-and-touch]

Mobile layout is built for pointer input as well as the keyboard:

* Click a row in the list to select it
* Click **Connect** in the host detail panel to connect
* On the keys tab, click **Add to server** in the detail panel to install a public key

Arrow keys and `j` / `k` still work for moving through the list.

## When you might see it [#when-you-might-see-it]

* SSH from a phone or tablet terminal app
* A tmux or screen pane that is only a few dozen columns wide
* A split editor terminal that does not leave much horizontal space

For fully headless or scripted workflows, use the [CLI](/docs/features/cli) instead of the TUI.


---
Full docs index: https://bast.sh/llms.txt

---

# Keyboard shortcuts (https://bast.sh/docs/features/shortcuts)


Press `?` inside Bast for the in-app reference. Press `v` for version info, credits, and update hints.

## Navigation [#navigation]

| Key                    | Action                                                           |
| ---------------------- | ---------------------------------------------------------------- |
| `↑` / `↓` or `j` / `k` | Move selection                                                   |
| Click / tap list row   | Select item ([mobile layout](/docs/features/mobile-view))        |
| `1`                    | Switch to hosts tab                                              |
| `2`                    | Switch to keys tab                                               |
| `3`                    | Switch to sync tab                                               |
| `4`                    | Switch to files tab                                              |
| `/`                    | Search                                                           |
| `r`                    | Reload config from disk (or refresh sync status on the Sync tab) |
| `?`                    | Toggle help                                                      |
| `v`                    | About and version info                                           |
| `q`                    | Quit                                                             |

## Hosts [#hosts]

| Key                     | Action                                                                    |
| ----------------------- | ------------------------------------------------------------------------- |
| `Enter`                 | Connect to selected host, or add selected history suggestion              |
| Click / tap **Connect** | Connect on narrow terminals ([mobile layout](/docs/features/mobile-view)) |
| `a`                     | Add a host                                                                |
| `e`                     | Edit selected host, or review selected history suggestion                 |
| `m`                     | Move selected local host to a group                                       |
| `x`                     | Dismiss selected history suggestion                                       |
| `d`                     | Delete selected host                                                      |
| `p`                     | Promote an external host into Bast-managed config                         |
| `f`                     | Toggle favorite                                                           |
| `F`                     | Open Files for the selected host                                          |
| `h`                     | Hide or show selected host                                                |
| `.`                     | Toggle hidden hosts in the list                                           |
| `Space`                 | Collapse or expand group, including Suggested                             |
| `s`                     | Cycle sort mode                                                           |
| `K`                     | Remove known-host entry                                                   |

## Keys [#keys]

| Key | Action                                                         |
| --- | -------------------------------------------------------------- |
| `a` | Generate a key                                                 |
| `i` | Import a key                                                   |
| `e` | Edit public key comment                                        |
| `d` | Delete selected key                                            |
| `u` | Add public key to a server                                     |
| `x` | Export key files                                               |
| `p` | Promote an external key, or change passphrase on a managed key |
| `c` | Copy public key                                                |

## Sync [#sync]

| Key     | Action                                                     |
| ------- | ---------------------------------------------------------- |
| `Enter` | Open Vault or a cloud provider, or run the selected action |
| `Esc`   | Back to the sync list                                      |
| `r`     | Refresh sync status                                        |

See [Vault](/docs/features/vault) for encrypted Bast config sync, and [GCP](/docs/features/gcp) / [AWS](/docs/features/aws) / [Azure](/docs/features/azure) / [box.ascii.dev](/docs/features/box) for cloud host import.

## Files [#files]

| Key         | Action                                             |
| ----------- | -------------------------------------------------- |
| `Tab`       | Switch pane                                        |
| `w`         | Swap panes                                         |
| `L` / `R`   | Make focused pane local / remote                   |
| `h` / `l`   | Parent / enter directory                           |
| `Enter`     | Enter directory, or connect the selected host      |
| `j` / `k`   | Move                                               |
| `g` / `G`   | Top / bottom                                       |
| `f`         | Fuzzy jump                                         |
| `/`         | Path jump (or host search on a remote picker)      |
| `Space`     | Toggle mark                                        |
| `v`         | Start or finish range mark                         |
| `c` / `m`   | Copy / move to the other pane                      |
| `d`         | Delete (with confirmation)                         |
| `a`         | Create directory                                   |
| `r`         | Rename                                             |
| `i`         | File info                                          |
| `p`         | Permissions (chmod)                                |
| `t`         | Open a shell in the current directory              |
| `.`         | Toggle hidden files                                |
| `D`         | Disconnect remote                                  |
| `Esc`       | Clear marks, else disconnect, else return to Hosts |
| `Esc` / `x` | Cancel transfer or connect                         |

Click a pane to focus it, a row to select it, and the same row again to enter or connect. Scroll wheel moves the pane under the pointer.

See [Files](/docs/features/files) for transfer and auth notes.

## During SSH [#during-ssh]

| Action            | Result                                                   |
| ----------------- | -------------------------------------------------------- |
| `exit`            | Close SSH session and quit Bast                          |
| `Enter` then `~.` | Force-close a stuck SSH session and return to the picker |


---
Full docs index: https://bast.sh/llms.txt

---

# AWS (https://bast.sh/docs/features/aws)


The **Sync** tab (`3`) imports running Linux EC2 instances into Bast. Synced hosts remain ordinary OpenSSH entries, while their connection details, label, and group stay owned by AWS sync.

Bast uses **AWS CLI v2** on your machine. It does not store AWS credentials or use a separate cloud agent. Discovery, EC2 Instance Connect keys, and private tunnels run through the AWS CLI profiles you already use.

Bast supports **GCP**, **AWS**, **Azure**, and **box.ascii.dev** through each provider's native CLI.

## Requirements [#requirements]

* AWS CLI v2 on your `PATH`
* At least one authenticated AWS CLI profile
* IAM access to discover EC2 instances and their connection routes
* A running Linux instance with SSH available
* For direct connections: a public IPv4 or IPv6 address reachable on port 22
* For private-only instances: an active [EC2 Instance Connect Endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-with-ec2-instance-connect-endpoint.html) with working routes and security groups

Windows and stopped instances are skipped.

## Install and authenticate AWS CLI [#install-and-authenticate-aws-cli]

Install AWS CLI v2 using the [official AWS instructions](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), then verify it:

```bash
aws --version
```

For browser-based console credentials on a current CLI:

```bash
aws login --profile default
```

For IAM Identity Center:

```bash
aws configure sso --profile production
aws sso login --profile production
```

Check the profiles Bast will find and confirm the identity behind one of them:

```bash
aws configure list-profiles
aws sts get-caller-identity --profile default
```

`default`, `production`, and similar names are AWS CLI profiles. Bast uses them as the second level of the managed host group.

## Connect AWS [#connect-aws]

1. Open Bast and press `3` for Sync.
2. Select **AWS** and press Enter.
3. Choose **Connect** or **Sync now**.

By default Bast scans every configured profile and every enabled region. Use **Profile filter** or **Region filter** before syncing when an account is large or a profile should stay out of Bast.

Discovery fails closed. If a selected profile or region cannot be scanned, Bast reports an incomplete discovery and keeps the previous synced inventory instead of deleting hosts from a partial result.

## What gets created [#what-gets-created]

Each instance becomes an SSH host under:

```text
~/.ssh/bast/sync/aws/config
```

The host picker groups instances by the AWS CLI profile and region used to discover them:

```text
Amazon EC2 / <profile> / <region>
  instance-name
```

For example:

```text
Amazon EC2 / default / eu-west-2
  web-01
```

Detail shows **AWS synced**. Connection settings, group, and label are read-only. Favoriting and hiding still work. Bast uses the EC2 `Name` tag as the label, falling back to the instance ID when no name is set.

## How Bast connects [#how-bast-connects]

On connect (TUI Enter or `bast connect` / `bast <label>`), Bast confirms the AWS account and instance, prepares SSH authentication, then launches your system `ssh`.

| Situation                              | Behavior                                                                            |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| Public IPv4 or IPv6                    | Direct OpenSSH connection                                                           |
| Private address only                   | `ProxyCommand` through an EC2 Instance Connect Endpoint in the same VPC             |
| Matching EC2 launch key exists locally | Uses that private key with `IdentitiesOnly yes`                                     |
| Launch key is missing                  | Publishes Bast's SSH public key through EC2 Instance Connect immediately before SSH |
| Instance launched without a key pair   | Uses the same EC2 Instance Connect path, when the AMI and IAM policy support it     |

Bast infers common AMI users such as `ubuntu` and `ec2-user`. Set **Default SSH user** in the AWS submenu when the AMI does not expose enough information to identify the user.

### EC2 launch keys [#ec2-launch-keys]

When the instance has an EC2 key pair, keep its private key under a matching name. For an EC2 key pair named `production`, Bast checks:

```text
~/.ssh/bast/keys/production
~/.ssh/bast/keys/production.pem
~/.ssh/bast/keys/production.key
~/.ssh/production
~/.ssh/production.pem
~/.ssh/production.key
```

The file must contain a private key. On macOS and Linux, restrict a downloaded key before connecting:

```bash
chmod 400 ~/.ssh/production.pem
```

AWS does not provide the private half of an existing EC2 key pair again. If it is unavailable, Bast tries EC2 Instance Connect rather than guessing another identity.

### No launch key pair [#no-launch-key-pair]

An instance can be launched with **Proceed without a key pair** when its AMI is configured for another login method. For Bast, that method is [EC2 Instance Connect](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-connect-prerequisites.html).

When no matching launch key exists, Bast:

1. Creates `~/.ssh/bast/aws_compute` if needed.
2. Sends its public key to the instance with `ec2-instance-connect:SendSSHPublicKey`.
3. Starts OpenSSH while AWS makes that key available for 60 seconds.

The 60-second limit applies to starting authentication. An established SSH session continues normally.

## IAM permissions [#iam-permissions]

Sync uses these AWS API actions:

```text
sts:GetCallerIdentity
ec2:DescribeRegions
ec2:DescribeInstances
ec2:DescribeImages
ec2:DescribeInstanceConnectEndpoints
```

Connections may additionally require:

```text
ec2-instance-connect:SendSSHPublicKey
ec2-instance-connect:OpenTunnel
```

`SendSSHPublicKey` is required only when Bast cannot use the EC2 launch key. `OpenTunnel` is required only for a private instance reached through an EC2 Instance Connect Endpoint. Scope both permissions to the intended instances, endpoints, tags, and OS users where possible. See AWS's guidance for [EC2 Instance Connect IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-connect-configure-IAM-role.html) and [endpoint permissions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/permissions-for-ec2-instance-connect-endpoint.html).

## AWS settings [#aws-settings]

Inside the AWS submenu:

| Action                     | Purpose                                                  |
| -------------------------- | -------------------------------------------------------- |
| Sync now                   | Re-run discovery and refresh SSH config                  |
| Connect / Disconnect       | Enable sync, or turn it off and remove generated hosts   |
| Enable / Disable auto-sync | Sync when the TUI opens (off by default)                 |
| Default SSH user           | Override AMI username inference                          |
| Profile filter             | Comma-separated AWS CLI profiles; blank = all configured |
| Region filter              | Comma-separated AWS regions; blank = all enabled         |
| Refresh status             | Reload profiles and last-sync information                |

Press Esc to return to the provider list.

## CLI [#cli]

```bash
bast sync aws                              # discover and write hosts
bast sync status                           # profiles, filters, last sync, errors
bast sync disable aws                      # turn off and remove AWS sync hosts
bast sync aws --json
bast sync status --json
bast connect aws_default_eu-west-2_web-01  # prepare AWS access, then ssh
```

## Re-sync and cleanup [#re-sync-and-cleanup]

Press `r` on the Sync tab (or run `bast sync aws`) after creating, deleting, or changing EC2 instances. Disconnecting AWS removes the generated AWS sync config and its Include line. It does not affect Bast-managed hosts, EC2 instances, security groups, endpoints, or key pairs.

`~/.ssh/bast/aws_compute` remains available for later EC2 Instance Connect sessions. Bast does not create endpoints, change security groups, start instances, or modify AWS credentials.

## Troubleshooting [#troubleshooting]

| Error or missing host            | Check                                                                                     |
| -------------------------------- | ----------------------------------------------------------------------------------------- |
| No AWS profiles selected         | Run `aws configure list-profiles`, then clear or update the profile filter                |
| Authentication failure           | Refresh `aws login` or `aws sso login` for the named profile                              |
| Incomplete AWS discovery         | Confirm every selected profile can read every selected region                             |
| SSH user could not be determined | Set **Default SSH user** to the AMI user, such as `ubuntu` or `ec2-user`                  |
| `SendSSHPublicKey` denied        | Check IAM and confirm EC2 Instance Connect is installed on the AMI                        |
| Private instance missing         | Confirm an active endpoint exists in the VPC and the instance has a private address       |
| Private SSH fails                | Check endpoint routes, endpoint and instance security groups, and `OpenTunnel` permission |


---
Full docs index: https://bast.sh/llms.txt

---

# Azure (https://bast.sh/docs/features/azure)


The **Sync** tab (`3`) imports running standalone Linux virtual machines from Azure. Synced hosts remain ordinary OpenSSH entries, while their connection details, label, and group stay owned by Azure sync.

Bast uses the native &#x2A;*Azure CLI (`az`)** on your machine. It does not store Azure credentials, use an Azure SDK, or run a cloud agent.

Bast supports **GCP**, **AWS**, **Azure**, and **box.ascii.dev** through each provider's native CLI.

## Requirements [#requirements]

* Azure CLI 2.62 or later on your `PATH`
* At least one enabled subscription available through `az login`
* A local private key matching a public key in the VM model, or Microsoft Entra SSH login enabled on the VM
* For Microsoft Entra certificates: the Azure CLI `ssh` extension
* For private-only VMs: a Standard or Premium Azure Bastion with native-client tunnelling enabled, plus the Azure CLI `bastion` extension

Install the optional extensions when you need those connection methods:

```bash
az extension add --name ssh
az extension add --name bastion
```

## Authenticate Azure CLI [#authenticate-azure-cli]

Install Azure CLI using the [official Microsoft instructions](https://learn.microsoft.com/cli/azure/install-azure-cli), then sign in:

```bash
az version
az login
az account list --output table
```

Bast scans enabled subscriptions in the Azure cloud currently selected by the CLI. Subscription filters accept exact subscription names or IDs.

## Connect Azure [#connect-azure]

1. Open Bast and press `3` for Sync.
2. Select **Azure** and press Enter.
3. Choose **Connect** or **Sync now**.

By default Bast scans every enabled subscription and resource group. Use **Subscription filter** or **Resource group filter** before syncing when only part of the account should appear.

Discovery is fail-closed per subscription. If one selected subscription cannot be scanned, Bast keeps that subscription's previous synced hosts. Subscriptions that were scanned successfully still reconcile normally. If no selected subscription can be confirmed, Bast leaves the generated inventory unchanged and reports an incomplete discovery.

## What gets created [#what-gets-created]

Each VM becomes an SSH host under:

```text
~/.ssh/bast/sync/azure/config
```

The host picker groups VMs by subscription and resource group:

```text
Microsoft Azure / <subscription> / <resource group>
  vm-name
```

Detail shows **Azure synced**. Connection settings, group, and label are read-only. Favoriting and hiding still work.

Bast imports only running standalone Linux VMs with a usable route. Windows VMs, stopped VMs, virtual machine scale sets, Azure Arc machines, and VMs without either a public address or a matching Azure Bastion route are not imported.

## How Bast connects [#how-bast-connects]

On connect (TUI Enter or `bast connect` / `bast <label>`), Bast rechecks the VM and prepares authentication before launching your system `ssh`.

| Situation                                            | Behavior                                                              |
| ---------------------------------------------------- | --------------------------------------------------------------------- |
| Public IPv4 or IPv6                                  | Direct OpenSSH connection                                             |
| Private address only                                 | OpenSSH `ProxyCommand` through Azure Bastion                          |
| Deployment public key matches a local key            | Uses the local private key with `IdentitiesOnly yes`                  |
| No matching local key and Entra SSH login is enabled | Requests a short-lived Entra OpenSSH certificate with `az ssh config` |
| Neither method is available                          | Stops with an actionable access error; the VM is not modified         |

### Local deployment keys [#local-deployment-keys]

Bast compares public keys in the Azure VM model with `.pub` files under:

```text
~/.ssh/bast/keys
~/.ssh
```

The matching private key must exist beside its `.pub` file. Bast rechecks the VM on every connection rather than trusting stale sync metadata.

### Microsoft Entra certificates [#microsoft-entra-certificates]

When no local key matches, Bast checks for `AADSSHLoginForLinux` and uses the Azure CLI `ssh` extension to request an OpenSSH certificate. Azure CLI material is kept under:

```text
~/.ssh/bast/azure
```

The certificate is refreshed for each connection. The user must have the **Virtual Machine User Login** or **Virtual Machine Administrator Login** role at an applicable scope.

Bast does not install the Entra extension or assign Azure roles.

### Azure Bastion [#azure-bastion]

Private VMs require an existing Bastion attached to the same virtual network. The Bastion must use Standard or Premium SKU and have native-client tunnelling enabled.

The generated SSH host uses an internal Bast `ProxyCommand` that starts `az network bastion tunnel`, connects OpenSSH to its local port, and shuts the tunnel down with the SSH session. Required access includes Reader permission on the VM, NIC, and Bastion resource, plus any VM login role required by the selected authentication method.

Bast does not create or update Bastion resources, virtual networks, network security groups, routes, public addresses, or VMs.

## Azure settings [#azure-settings]

Inside the Azure submenu:

| Action                     | Purpose                                                           |
| -------------------------- | ----------------------------------------------------------------- |
| Sync now                   | Re-run discovery and refresh SSH config                           |
| Connect / Disconnect       | Enable sync, or turn it off and remove generated hosts            |
| Enable / Disable auto-sync | Sync when the TUI opens (off by default)                          |
| Default SSH user           | Override the VM admin username for local-key connections          |
| Subscription filter        | Comma-separated exact names or IDs; blank = all enabled           |
| Resource group filter      | Comma-separated exact names; blank = all                          |
| Refresh status             | Reload subscriptions, extension checks, and last-sync information |

Press Esc to return to the provider list.

## CLI [#cli]

```bash
bast sync azure
bast sync status
bast sync disable azure
bast sync azure --json
bast sync status --json
bast connect azure_Production_apps_web
```

## Re-sync and cleanup [#re-sync-and-cleanup]

Press `r` on the Sync tab (or run `bast sync azure`) after creating, deleting, moving, or changing a VM. Disconnecting Azure removes the generated Azure sync config and its Include line. It does not affect Bast-managed hosts or Azure resources.

The `~/.ssh/bast/azure` directory remains available for later Entra connections. Bast does not modify Azure CLI credentials or append keys through VMAccess.

## Troubleshooting [#troubleshooting]

| Error or missing host            | Check                                                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| No Azure subscriptions selected  | Run `az login` and `az account list`, then clear or update the subscription filter                               |
| Azure CLI 2.62 required          | Upgrade Azure CLI using Microsoft's installation instructions                                                    |
| Incomplete Azure discovery       | Confirm Reader access to every selected subscription, VM, NIC, and Bastion resource                              |
| Private VM missing               | Confirm a Standard or Premium Bastion exists in the same virtual network with tunnelling enabled                 |
| Bastion extension required       | Run `az extension add --name bastion`                                                                            |
| SSH extension required           | Run `az extension add --name ssh`                                                                                |
| Entra login is not enabled       | Install `AADSSHLoginForLinux` through your Azure administration workflow, or restore the VM's matching local key |
| Entra access denied              | Check the Virtual Machine User Login or Administrator Login role and Conditional Access requirements             |
| SSH user could not be determined | Set **Default SSH user** in the Azure submenu                                                                    |


---
Full docs index: https://bast.sh/llms.txt

---

# box.ascii.dev (https://bast.sh/docs/features/box)


The **Sync** tab (`3`) imports [ASCII Box](https://box.ascii.dev/) sandboxes into Bast. Synced boxes show up in the host picker under **Box**, stay connectable with your system `ssh`, and keep connection details owned by Box sync.

Bast talks to Box through the native **`box` CLI** on your machine. There is no separate Bast cloud agent or Go SDK. Auth, list, stop, resume, and SSH key authorization all use the same CLI you already use with [box.ascii.dev](https://box.ascii.dev/).

Bast supports **GCP**, **AWS**, **Azure**, and **box.ascii.dev** through each provider's native CLI.

## Requirements [#requirements]

* ASCII Box CLI (`box`) on your `PATH` (the installer also places it at `~/.ascii/bin/box`)
* An authenticated Box account (`box login` / `box onboard`)
* Network access to create, stop, resume, and SSH into your boxes

## Connect box.ascii.dev [#connect-boxasciidev]

1. Open Bast and press `3` for Sync.
2. Select **box.ascii.dev** and press Enter.
3. Choose **Connect** or **Sync now**.

If the Box CLI is already installed and logged in, Bast **auto-connects** on TUI start and when you run `bast sync status`, unless you previously chose **Disconnect** (sticky opt-out via `bast sync disable box`).

Sign in with the usual CLI:

```bash
box login
box status
```

## What gets created [#what-gets-created]

Each box becomes an SSH host Bast writes under:

```
~/.ssh/bast/sync/box/config
```

Your managed Bast config includes that file so OpenSSH (and Bast) can see the hosts. In the picker they are grouped as:

```
Box
  box-name
```

Running boxes show **Box synced**. Stopped or archiving boxes stay in the same group, rendered muted, with detail **Box stopped**. Connection settings, group, and label are owned by sync, so edit (`e`), delete (`d`), move, favorite, and hide are blocked. Manage lifecycle from Sync or the Box host keys below.

## How Bast connects [#how-bast-connects]

On connect (TUI Enter or `bast connect` / `bast <label>`), Bast prepares SSH access, then launches your system `ssh`.

| Situation           | Behavior                                                        |
| ------------------- | --------------------------------------------------------------- |
| Running box with IP | Direct SSH as `user` with `~/.ssh/ascii_box_ed25519`            |
| Stopped box         | Enter resumes the box, refreshes sync, then SSHs in             |
| Missing local key   | Ensures `~/.ssh/ascii_box_ed25519` and authorizes it on the box |

SSH user is always `user`. There is no default-user setting for Box.

## Stopping and archiving [#stopping-and-archiving]

Stopping a box snapshots it and pauses billing (`archiving` → `archived`). That can take a few minutes. Bast keeps the host visible and muted while the box is stopping, then keeps it under **Box** so you can resume later.

## box.ascii.dev settings [#boxasciidev-settings]

Inside the box.ascii.dev submenu:

| Action                     | Purpose                                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------- |
| Sync now                   | Re-run discovery and refresh SSH config                                                           |
| New box                    | Create a sandbox (`small` / `default` / `large`)                                                  |
| Connect / Disconnect       | Enable sync, or turn it off and remove generated hosts (Disconnect also opts out of auto-connect) |
| Enable / Disable auto-sync | Sync when the TUI opens                                                                           |
| Refresh status             | Reload account and last-sync info                                                                 |

Press Esc to return to the provider list.

## Host keys (Hosts tab) [#host-keys-hosts-tab]

With a Box host selected:

| Key   | Action                                               |
| ----- | ---------------------------------------------------- |
| Enter | Connect (resume first if stopped)                    |
| `r`   | Resume only (when stopped)                           |
| `o`   | Stop (when running; confirms with `stop`)            |
| `n`   | Fork from the latest snapshot (confirms with `fork`) |
| `F`   | Open Files (SFTP) when the box is reachable          |

## CLI [#cli]

```bash
bast sync box                 # discover and write hosts
bast sync status              # account, last sync, errors
bast sync disable box         # turn off, remove sync hosts, sticky opt-out
bast sync box --json

bast box new [--type small|default|large] [--ttl seconds | --no-auto-stop] [--no-env]
bast box fork <host|id> [--type small|default|large] [--no-env]
bast box stop <host|id>
bast box resume <host|id> [--type small|default|large] [--no-env]

bast connect box_mybox        # banner + Box access prepare, then ssh
```

## Re-sync and cleanup [#re-sync-and-cleanup]

Press `r` on the Sync tab (or run `bast sync box`) after you create, stop, or resume boxes outside Bast. Disconnecting box.ascii.dev removes the generated sync config and the Include line Bast added for it. Your Bast-managed hosts and keys are left alone. `~/.ssh/ascii_box_ed25519` is left in place if Bast created it.


---
Full docs index: https://bast.sh/llms.txt

---

# GCP (https://bast.sh/docs/features/gcp)


The **Sync** tab (`3`) pulls servers from cloud providers into Bast. Synced hosts show up in the host picker under a provider group, stay connectable with your system `ssh`, and keep connection details owned by the provider. You do not edit them like Bast-managed hosts.

Bast talks to Google Cloud through the native **`gcloud` CLI** on your machine. There is no separate Bast cloud agent or custom API client. Auth, project access, and IAP tunnels all use the same tools you already use with `gcloud compute ssh`.

Bast supports **GCP**, **AWS**, **Azure**, and **box.ascii.dev** through each provider's native CLI.

## Requirements [#requirements]

* Google Cloud SDK (`gcloud`) on your `PATH`
* At least one authenticated account (`gcloud auth login`), and/or a service account JSON key
* IAM that can list projects and Compute Engine instances
* For private VMs: [IAP TCP forwarding](https://cloud.google.com/iap/docs/using-tcp-forwarding) allowed to the instance

## Connect GCP [#connect-gcp]

1. Open Bast and press `3` for Sync.
2. Select **GCP** and press Enter.
3. Choose **Connect** or **Sync now**.

Bast discovers every authenticated `gcloud` account, lists accessible projects, and imports running Linux instances. Windows guests and stopped VMs are skipped.

Add more Google accounts with the usual CLI:

```bash
gcloud auth login
gcloud auth login other@example.com
```

## What gets created [#what-gets-created]

Each instance becomes an SSH host Bast writes under:

```
~/.ssh/bast/sync/gcp/config
```

Your managed Bast config includes that file so OpenSSH (and Bast) can see the hosts. In the picker they are grouped as:

```
Google Cloud / <project name>
  instance-name
```

Detail shows **GCP synced**. Connection settings, group, and label are owned by sync, so edit (`e`) and delete (`d`) are blocked. Favoriting and hiding still work. When the friendly label differs from the SSH alias, detail also shows **SSH name** (the `Host` alias used by `ssh`).

## How Bast connects [#how-bast-connects]

On connect (TUI Enter or `bast connect` / `bast <label>`), Bast prepares SSH access, then launches your system `ssh`. The same Bast connection banner appears in both paths, with muted progress lines while GCP work runs.

| Situation                    | Behavior                                                                                                                                                                    |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Public IP                    | Direct SSH to the external address                                                                                                                                          |
| Private only                 | `ProxyCommand` via `gcloud compute start-iap-tunnel`                                                                                                                        |
| Local key already authorized | Uses that key. Bast prefers a matching key in `~/.ssh/bast/keys` or `~/.ssh` over creating a Google key                                                                     |
| Metadata `ssh-keys`          | Matches the public key to a local private key, then sets `User` + `IdentityFile`                                                                                            |
| OS Login                     | Uses a local key already on your OS Login profile when possible; otherwise registers `~/.ssh/google_compute_engine`                                                         |
| No matching local key        | Ensures `~/.ssh/google_compute_engine` (like `gcloud compute ssh`), publishes it to instance/project metadata or OS Login if needed, then waits briefly for the guest agent |

Publishing a new key can take a few seconds. Bast explains that in the connection status lines (for example when registering an OS Login key or waiting for the guest agent). If the key is already present, Bast skips publish and wait.

If Auth in the detail panel says the user is unknown, set a **Default SSH user** in the GCP submenu (or put the right key on the VM / OS Login profile).

## GCP settings [#gcp-settings]

Inside the GCP submenu:

| Action                           | Purpose                                                |
| -------------------------------- | ------------------------------------------------------ |
| Sync now                         | Re-run discovery and refresh SSH config                |
| Connect / Disconnect             | Enable sync, or turn it off and remove generated hosts |
| Enable / Disable auto-sync       | Sync when the TUI opens (off by default)               |
| Default SSH user                 | Used when metadata / OS Login does not imply a user    |
| Project filter                   | Comma-separated project IDs; blank = all accessible    |
| Add / Remove service account key | JSON key paths for projects your user login cannot see |
| Refresh status                   | Reload accounts and last-sync info                     |

Press Esc to return to the provider list.

## CLI [#cli]

```bash
bast sync gcp                 # discover and write hosts
bast sync status              # accounts, last sync, errors
bast sync disable gcp         # turn off and remove sync hosts
bast sync gcp --json
bast sync status --json
bast connect gcp_myproj_web   # banner + GCP access prepare, then ssh
```

## Re-sync and cleanup [#re-sync-and-cleanup]

Press `r` on the Sync tab (or run `bast sync gcp`) after you create or delete VMs. Disconnecting GCP removes the generated sync config and the Include line Bast added for it. Your Bast-managed hosts and keys are left alone. `~/.ssh/google_compute_engine` is left in place if Bast created it.


---
Full docs index: https://bast.sh/llms.txt

---

# Vault (https://bast.sh/docs/features/vault)


Vault syncs **Bast-managed** hosts, keys, and metadata between your machines. It is separate from cloud provider sync (GCP / AWS / Azure / box.ascii.dev), which imports hosts into local SSH config.

Ciphertext is stored by Bast. The encryption passphrase never leaves your machine. Bast keeps a local copy in `~/.config/bast/vault-passphrase` (mode `0600`) so linked machines stay unlocked across launches. That file is a local secret equivalent to an unlocked key: protect the account that can read `~/.config/bast`. Log out deletes it.

## What syncs [#what-syncs]

| Included                                                | Not included                                       |
| ------------------------------------------------------- | -------------------------------------------------- |
| Managed hosts in `~/.ssh/bast/config`                   | External hosts in `~/.ssh/config`                  |
| Bast-managed keys in `~/.ssh/bast/keys/`                | External keys under `~/.ssh`                       |
| Host labels, groups, tags, notes, preferences           | Cloud VM inventory files                           |
| Cloud integration *settings* (filters, auto-sync flags) | Cloud credentials, SA JSON paths, last-sync errors |

External hosts and keys stay local until you [promote](#promote) them into Bast-managed ownership.

## Link a machine [#link-a-machine]

From the Sync tab, open **Vault**, or use the CLI:

```bash
bast vault login --email you@example.com
```

1. Enter your email. Bast sends a one-time code.
2. Paste the code in the terminal.
3. Choose a vault passphrase (and confirm it).

Lost passphrase means the remote vault cannot be decrypted. Bast cannot recover it.

On first link, local and remote state are merged by stable IDs (`ManagedID` for hosts, key fingerprint for keys). True conflicts (same alias, different managed IDs) open a chooser in the TUI: keep this machine, keep remote, or cancel. Cancelling leaves the machine unlinked so you can link again. From the CLI:

```bash
bast vault pull --mode replace_local   # keep remote
bast vault pull --mode replace_remote  # keep this machine
```

## Everyday use [#everyday-use]

In the TUI (Sync → Vault), **Sync now** pulls remote changes and then pushes local ones. If the same alias or key name exists on both sides with different identities, Bast opens that same keep-local / keep-remote chooser instead of failing with a dead-end status. Linked machines also pull in the background after hosts load when a passphrase is available, and local edits debounce a push after a few seconds (push merges with the remote vault first). Opening Bast never waits on the network to show your hosts.

CLI still exposes pull and push separately:

```bash
bast vault status
bast vault pull
bast vault push
bast vault logout
bast vault passphrase          # rotate (needs current passphrase)
bast vault passphrase --force  # reset: encrypt this machine and overwrite remote
```

### Change or reset the passphrase [#change-or-reset-the-passphrase]

**Rotate** when you still know the current passphrase. Bast decrypts the remote vault, re-encrypts it with the new passphrase, and uploads it:

```bash
bast vault passphrase
```

In the TUI: Sync → Vault → **Rotate passphrase**. If the session is already unlocked, only the new passphrase is requested.

**Force reset** when the old passphrase is lost, or you want this machine’s managed hosts/keys to become the remote vault under a new passphrase. This does not need the old passphrase. Remote-only data that is not on this machine is discarded:

```bash
bast vault passphrase --force
```

In the TUI: Sync → Vault → **Reset passphrase**, type `RESET`, then enter the new passphrase twice.

Other linked machines must unlock (or reset) with the new passphrase afterward.

## Self-hosting [#self-hosting]

By default Bast talks to `https://bast.sh`. To keep vault storage on your own infrastructure, [self-host the web app](/docs/reference/self-hosting) and set the API base in Sync → Vault → **API base URL**, with `bast vault login --api https://your.origin`, or with `BAST_VAULT_API`.

## Promote [#promote]

External hosts and keys cannot enter the vault until Bast owns them.

| Surface   | Action                                                                |
| --------- | --------------------------------------------------------------------- |
| Hosts tab | `p` on an external host, or the detail affordance                     |
| Keys tab  | `p` on an external key (managed keys still use `p` for passphrase)    |
| CLI       | `bast hosts promote <host>` · `bast keys promote <key> [--name name]` |

Promote copies into Bast-managed config/keys. The original external SSH config block or key file is left in place.

## Encryption [#encryption]

* Passphrase → Argon2id → 256-bit key
* Vault document sealed with XChaCha20-Poly1305
* Server stores only the opaque envelope (plus revision metadata in Redis and the blob in object storage)

Session tokens live in `~/.config/bast/vault-session.json` (mode `0600`) and authorize upload/download of ciphertext only.


---
Full docs index: https://bast.sh/llms.txt