> ## 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 setup ssh

> Record the SSH keys you use to reach agent VMs with murmur ssh, generate one when needed, and upload them for dashboard spawns.

Sets up SSH access to your agents' VMs with `murmur setup ssh`. It records the public keys of your local SSH key pairs so [`murmur ssh`](https://docs.murmur.dev/cli/ssh) can connect, and offers to upload them so agents spawned from the [dashboard](https://docs.murmur.dev/guides/dashboard.md) authorize them too. Private keys never leave your machine.

If no home or repository configuration exists, the command signs you in, saves your selected tenant under `~/.murmur/`, and continues recording SSH keys beside that home configuration.

Environment-only identities do not save home configuration. To record credentials locally, set `MURMUR_CONFIG` to an existing file, or unset `MURMUR_IDENTITY_TOKEN` and `MURMUR_AUTH_METHOD` and run [`murmur login`](https://docs.murmur.dev/cli/login).

## Synopsis

```bash theme={null}
murmur setup ssh
```

This command takes no positional arguments or flags. Use `--help` for usage.

## What it does

1. **Finds your key pairs.** Scans `~/.ssh` for public keys (`*.pub`) that have a matching private key.
2. **Offers to generate one when there are none.** Choose **Generate an ed25519 key now** to run `ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519`, or **Skip**. Skipping, or a failed `ssh-keygen`, leaves any keys already recorded in place.
3. **Records the public keys.** Sets `ssh_public_keys` in `murmur.local.yaml`, next to the `murmur.yaml` that murmur loads for the current directory, and creates the file if it does not exist. Every other setting in the file is left as it was.
4. **Asks whether to upload them.** `Upload your SSH public keys so you can SSH into agents spawned from the dashboard?` defaults to yes. Yes replaces the SSH keys on your [user](https://docs.murmur.dev/catalog/user.md) record and changes nothing else in your profile. The upload uses your existing Murmur sign-in.

The command records the keys locally before uploading them. If the upload fails, the keys are still recorded, so `murmur ssh` keeps working for agents you spawn from the CLI. Re-run the command to retry the upload.

## Where the keys are used

| Spawned from | Keys authorized on the VM |
| - | - |
| The CLI or MCP server | The `ssh_public_keys` in your local `murmur.local.yaml`, sent with each spawn. |
| The dashboard | The SSH keys on your uploaded [user](https://docs.murmur.dev/catalog/user.md) record. |

A key change applies to agents spawned afterward. Running agents keep the keys they started with.

## Examples

### Record existing keys and upload them

```bash theme={null}
murmur setup ssh
```

```
? Upload your SSH public keys so you can SSH into agents spawned from the dashboard? [Y/n]
  ✓ Recorded 2 SSH public key(s) in /home/alice/src/app/.murmur/murmur.local.yaml
  ✓ SSH public keys uploaded
```

### Generate a key on a new machine

```bash theme={null}
murmur setup ssh
```

```
? No SSH keys found in ~/.ssh. SSH keys let you connect to agent VMs.
    [1] Generate an ed25519 key now (runs ssh-keygen)
    [2] Skip — you won't be able to SSH into agent VMs
```

Press Enter to generate the key, then answer the upload question.

## Errors

| Code | Meaning | What to do |
| - | - | - |
| `saving SSH keys requires a configuration file` | Murmur is configured only through environment variables, so there is no `murmur.local.yaml` to record into. | Set `MURMUR_CONFIG` to an existing file, or unset the environment identity variables and run [`murmur login`](https://docs.murmur.dev/cli/login). |
| `ssh-keygen: ...` | Key generation failed. The recorded keys were not changed. | Fix the reported problem, or generate a key yourself with `ssh-keygen -t ed25519`, then re-run. |
| `connect for SSH key upload: ...` or `upload SSH keys: ...` | The keys were recorded locally, but the upload failed. | Check that you are signed in ([`murmur login`](https://docs.murmur.dev/cli/login)) and re-run. |

## Related

* [`murmur ssh`](https://docs.murmur.dev/cli/ssh): connect to an agent's VM
* [`murmur setup`](https://docs.murmur.dev/cli/setup): list configuration subcommands
* [Local overlays](https://docs.murmur.dev/configuration/local-overlays.md): the `ssh_public_keys` field
* [User](https://docs.murmur.dev/catalog/user.md): the uploaded profile record


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