---
title: SSH commands
sidebarTitle: "SSH"
description: Connect to and serve sandboxes over SSH
icon: "lock"
---

SSH commands expose sandbox shells, remote commands, and SFTP through the SSH protocol. For usage flows, see [SSH](/sandboxes/ssh).

## msb ssh

Start a native SSH client session into a sandbox. With no remote command, this opens an interactive shell. With `--`, the remaining tokens are joined into the remote shell command.

```bash
msb ssh devbox
msb ssh devbox -- uname -a
msb ssh --name serve -- uptime
```

| Argument | Description |
|----------|-------------|
| `sandbox` | Sandbox name, up to 128 UTF-8 bytes |
| `--name NAME` | Explicit sandbox name, up to 128 UTF-8 bytes; useful when the name collides with `serve`, `authorize`, or `help` |
| `-- COMMAND...` | Remote command to run through the sandbox shell |

## msb ssh authorize

Add a public key to microsandbox's SSH authorization file.

```bash
msb ssh authorize --file ~/.ssh/id_ed25519.pub
msb ssh authorize --key "ssh-ed25519 AAAA... user@host"
cat ~/.ssh/id_ed25519.pub | msb ssh authorize --stdin
```

| Flag | Description |
|------|-------------|
| `--file PATH` | Read one public key from a file |
| `--key KEY` | Read one public key from the flag value |
| `--stdin` | Read one public key from stdin |

The default authorization file is `<MSB_HOME>/ssh/authorized_keys`, or `~/.microsandbox/ssh/authorized_keys` when `MSB_HOME` is unset. The file is created with private permissions.

## msb ssh serve

Serve a sandbox over SSH for external OpenSSH, SFTP, or `ProxyCommand` clients.

```bash
msb ssh serve devbox
msb ssh serve devbox --host 127.0.0.1 --port 2222
msb ssh serve devbox --stdio
```

| Flag | Description |
|------|-------------|
| `--host HOST` | Listener host. Defaults to `127.0.0.1` |
| `--port PORT` | Listener port. Defaults to `2222` |
| `--stdio` | Serve one SSH transport over stdin/stdout for OpenSSH `ProxyCommand` |

Listener mode accepts ordinary OpenSSH clients:

```bash
ssh -p 2222 root@127.0.0.1
sftp -P 2222 root@127.0.0.1
```

`--stdio` is for clients that spawn `msb` as a transport bridge:

```sshconfig
Host devbox.msb
  User root
  ProxyCommand msb ssh serve devbox --stdio
```

## msb ssh connect

Explicit subcommand form for native SSH client sessions.

```bash
msb ssh connect devbox
msb ssh connect devbox -- uname -a
```

| Argument | Description |
|----------|-------------|
| `sandbox` | Sandbox name, up to 128 UTF-8 bytes |
| `--name NAME` | Explicit sandbox name, up to 128 UTF-8 bytes |
| `-- COMMAND...` | Remote command to run through the sandbox shell |

## SSH state

| Path | Purpose |
|------|---------|
| `<sandbox-dir>/ssh/host_ed25519` | Per-sandbox SSH host private key, created on first serve |
| `<MSB_HOME>/ssh/authorized_keys` | Public keys allowed to connect |

When `MSB_HOME` is unset, `<MSB_HOME>` is `~/.microsandbox`.
