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

# murmur ssh

> Open a terminal on an agent's VM, attach to its running coding session, or execute a one-off remote command over SSH for debugging.

Opens an SSH connection to a running [agent's](/concepts/agents) VM. Use it to inspect the filesystem, watch logs, or attach directly to the agent's live coding session.

## Synopsis

```bash theme={null}
murmur ssh [flags] <slug> [-- <command...>]
```

Everything after `--` is executed as a command on the VM instead of opening an interactive shell.

## Arguments

| Name          | Type   | Required | Description                                                                     |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `slug`        | string | yes      | The [agent's](/concepts/agents) slug.                                           |
| `--attach`    | bool   | no       | Attach to the agent's `claude` tmux session. Default: `false`.                  |
| `-v`          | bool   | no       | Show SSH debug output. Default: `false`.                                        |
| `--workspace` | string | no       | [Workspace](/concepts/workspaces) name. Overrides the value from `murmur.yaml`. |

## Examples

### Open an interactive shell

```bash theme={null}
murmur ssh fix-auth
```

Opens a terminal on the [agent's](/concepts/agents) VM. You land in a standard shell and can browse the cloned repo, read logs, or run commands.

### Attach to the agent's coding session

```bash theme={null}
murmur ssh fix-auth --attach
```

Attaches to the `claude` tmux session where the [agent](/concepts/agents) is working. You see its live terminal output in real time. Detach with `Ctrl-b d`.

### Run a single command

```bash theme={null}
murmur ssh fix-auth -- git log --oneline -5
```

```
a1b2c3d Fix JWT expiry check
d4e5f6a Add token refresh test
7890abc Refactor auth middleware
bcd1234 Update go.mod
ef56789 Initial scaffold
```

Runs the command on the VM and exits. No interactive shell is opened.

### Verbose output for debugging

```bash theme={null}
murmur ssh fix-auth -v
```

Prints SSH connection diagnostics to stderr. Useful when a connection is hanging or failing.

## Errors

| Code                                 | Meaning                                                           | What to do                                                                                               |
| ------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `NOT_FOUND`                          | No [agent](/concepts/agents) with that slug exists.               | Check the slug. Use [`murmur ls`](/cli/ls) to list running [agents](/concepts/agents).                   |
| `UNAUTHENTICATED`                    | Identity token is missing or expired.                             | Run `murmur auth` or check your `murmur.local.yaml` configuration.                                       |
| `FAILED_PRECONDITION`                | The [agent's](/concepts/agents) VM is not running.                | The [agent](/concepts/agents) may be [sleeping](/concepts/agents). Run [`murmur wake`](/cli/wake) first. |
| `ssh is not supported on VMs`        | You ran `murmur ssh` from inside an [agent](/concepts/agents) VM. | Run this command from your laptop, not from a VM.                                                        |
| `no ssh_public_keys in local config` | No SSH keys are configured.                                       | Run `murmur setup` to register your SSH public keys.                                                     |

## Related

* [Agents](/concepts/agents) — concept overview
* [`murmur status`](/cli/status) — check an agent's phase and progress
* [`murmur port-forward`](/cli/port-forward) — tunnel local ports to the agent's VM
* [`murmur ls`](/cli/ls) — list running agents
* [`murmur wake`](/cli/wake) — restart a sleeping agent's VM