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 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 — How a device enrols, and what identifies one.
Device Not Appearing — When configuration is the cause.