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

# SSH

> SSH into a Lager Box

Open an interactive SSH session to a Lagerbox, or run a single command on it
and return.

## Syntax

```bash theme={null}
lager ssh [OPTIONS] [COMMAND]...
```

## Options

| Option      | Description                 |
| ----------- | --------------------------- |
| `--box BOX` | Lagerbox name or IP address |

## Arguments

| Argument  | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `COMMAND` | Optional command to run on the box. If omitted, an interactive shell is opened. |

***

## Usage

```bash theme={null}
# SSH to specific Lager Box (interactive shell)
lager ssh --box my-lager-box

# SSH to default Lager Box
lager ssh
```

### Run a command on the box

With a `COMMAND`, `lager ssh` behaves like `ssh user@host <command>`: it runs
the command on the box, streams its output back, and exits with the command's
exit code — no interactive shell. This is handy for scripting and one-off
checks.

```bash theme={null}
# Run a single command and return
lager ssh --box lab-lager-box -- cat /etc/lager/version

# Flags pass through; use `--` to separate them from lager's own options
lager ssh --box lab-lager-box -- ls -la /etc/lager

# Inspect the running containers
lager ssh --box lab-lager-box -- sudo docker ps
```

<Note>Use `--` to separate lager's options from the remote command whenever the
command contains its own dashed flags, so they aren't parsed as `lager`
options. The remote command's exit code is propagated as `lager ssh`'s exit
code, so it composes cleanly in scripts.</Note>

***

## How It Works

The command:

1. Resolves the Lager Box name to IP address
2. Looks up the SSH username (default: `lagerdata`)
3. Opens an interactive SSH session

***

## Username Resolution

SSH usernames are resolved in order:

1. Username stored with box configuration (`lager boxes add --user`)
2. Default username: `lagerdata`

To use a different username for a Lager Box:

```bash theme={null}
# Configure username when adding box
lager boxes add --name pi-lager-box --ip <BOX_IP> --user pi

# Or edit existing box
lager boxes edit --name pi-lager-box --user pi
```

***

## SSH Key Setup

For passwordless access, set up SSH keys:

```bash theme={null}
# Generate key if needed
ssh-keygen -t ed25519

# Copy to Lager Box
ssh-copy-id lagerdata@<box-ip>
```

***

## Examples

```bash theme={null}
# Quick interactive SSH access
lager ssh --box my-lager-box

# One-off commands (no interactive shell)
lager ssh --box my-lager-box -- cat /etc/lager/version
lager ssh --box my-lager-box -- sudo docker ps
lager ssh --box my-lager-box -- sudo ufw status
```

***

## Common Tasks via SSH

Each of these can be run as a one-liner with `lager ssh --box <box> -- <command>`,
or interactively after `lager ssh --box <box>`.

### Check Container Status

```bash theme={null}
lager ssh --box my-lager-box -- sudo docker ps -a
lager ssh --box my-lager-box -- sudo docker logs controller --tail 100
```

### View Lager Box Version

```bash theme={null}
lager ssh --box my-lager-box -- cat /etc/lager/version
```

### Check Disk Space

```bash theme={null}
lager ssh --box my-lager-box -- df -h
```

### View Firewall Status

```bash theme={null}
lager ssh --box my-lager-box -- sudo ufw status verbose
```

***

## Notes

* With no `COMMAND`, opens a fully interactive shell session (exit with `exit` or Ctrl+D)
* With a `COMMAND`, runs it on the box and exits with the command's exit code
* The session runs as a child process so Lager's cleanup hooks still fire
* Default Lager Box is used if `--box` not specified