# Agent Configuration

The agent is configured entirely through environment variables. Where you put them depends on the install method — the container’s environment, a systemd drop-in, `snap set`, or `/etc/rc.conf` on FreeBSD.

All names take the `SHELLHUB_` prefix. The required ones are also accepted without it, for compatibility with older setups.

## Required

| Variable                  | Meaning                                                            |
| ------------------------- | ------------------------------------------------------------------ |
| `SHELLHUB_SERVER_ADDRESS` | The server the agent connects to, e.g. `https://cloud.shellhub.io` |
| `SHELLHUB_PRIVATE_KEY`    | Path to the device’s private key. Generated on first run if absent |

**`SHELLHUB_PRIVATE_KEY` is the device’s identity.** Whatever else you get wrong, get this one right: it must be on storage that survives restarts, reflashes and container recreation, and it must be _unique per device_. A key shipped inside an image makes every unit built from that image claim to be the same device.

## Enrollment

| Variable                    | Default | Meaning                                                                                                                                                                                                            |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SHELLHUB_TENANT_ID`        | —       | Which namespace to join. Deprecated: the device lands pending until somebody accepts it. When empty, and nothing was persisted from an earlier pairing, the agent boots into pairing mode and waits to be accepted |
| `SHELLHUB_PROVISIONING_KEY` | —       | A reusable key from **Add Device** → **Fleet**, which names the namespace on its own and applies the key’s tags and ephemeral flag                                                                                 |

See [How a device enrols](https://docs.shellhub.io/manage/devices#how-a-device-enrols) for how these interact.

## Connection

| Variable                      | Default | Meaning                                                                              |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `SHELLHUB_KEEPALIVE_INTERVAL` | `30`    | Seconds between keepalives                                                           |
| `SHELLHUB_TRANSPORT_VERSION`  | `2`     | Transport. `1` uses HTTP-based revdial; `2` uses yamux multiplexing with multistream |

Leave the transport at its default unless you are working around something specific. Version 1 exists for compatibility with older servers.

## Identification

| Variable                      | Default | Meaning                                                      |
| ----------------------------- | ------- | ------------------------------------------------------------ |
| `SHELLHUB_PREFERRED_HOSTNAME` | —       | A hint for the device’s name, instead of the system hostname |
| `SHELLHUB_PREFERRED_IDENTITY` | `""`    | A hint for the device’s identity                             |

`SHELLHUB_PREFERRED_HOSTNAME` is worth setting on anything whose system hostname is not meaningful — a container with a random hostname, or a fleet where every unit reports the same one. The device name is what you type in an SSHID and what a legacy public key’s or firewall rule’s hostname filter matches against.

## Access

| Variable                        | Default | Meaning                                                                             |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `SHELLHUB_SINGLE_USER_PASSWORD` | —       | Password hash for single-user mode                                                  |
| `SHELLHUB_SIMPLE_USER_PASSWORD` | —       | **Legacy alias** for the above, a preserved typo. Use `SINGLE` in new configuration |

Generate the hash with `openssl passwd`. Single-user mode is for devices with no real user accounts to authenticate against.

## Where to go next

- [Managing Devices](https://docs.shellhub.io/manage/devices) — How a device enrols, and what identifies one.
- [Device Not Appearing](https://docs.shellhub.io/manage/devices/device-not-appearing) — When configuration is the cause.
