shellhub Documentation

1. You run ssh [email protected]@cloud.shellhub.io.
2. The connection reaches the ShellHub server.
3. The server parses the SSHID and resolves the namespace and the device.
4. It works out who you are — from the key you presented, a password, or an approval you
   confirm in the browser.
5. It authorizes the connection against the namespace's access policies.
6. It finds the connection the agent already has open.
7. Your terminal I/O is bridged down that connection to the agent.
8. The agent opens a shell on the device and joins it to the session.

Step 5 happens before the server mints anything for the agent, so a refused connection never
reaches the device at all.

The web terminal takes a different route in — your browser opens a WebSocket to the server
instead of an SSH connection — and exactly the same route out.

Where to go next Copy Chapter

• Ports and Connectivity — What has to be reachable, on both ends.
• Self-Hosted vs. Cloud — Which deployment fits you.
• Quickstart — Put the agent on a device.

Ui Apps Docs Src Pages About Ports And Connectivity (`ui/apps/docs/src/pages/about/ports-and-connectivity.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Ports and Connectivity Copy Chapter

import Callout from "../../components/Callout.astro";

Ports and Connectivity

This page exists so you can answer the network team's questions in one go.

On the device Copy Chapter

Outbound access to the ShellHub server's HTTP(S) address. That is the whole requirement.

The agent dials the address you gave it in SHELLHUB_SERVER_ADDRESS and holds that connection
open. It does not listen. Nothing has to be forwarded to it, published for it, or arranged in
advance.

That means all of the following are fine, with no configuration:

• Behind NAT, including carrier-grade NAT with no public address at all
• Behind a corporate firewall that only permits outbound web traffic
• Behind an HTTP proxy
• On a mobile or satellite link
• On a network you do not administer, such as a customer's

If a browser on that device could load a web page from your server, the agent can connect.

On the server Copy Chapter

Two details that surprise people:

The HTTPS port is not bound unless auto-SSL is on. The port mapping lives in an overlay that
is only applied when SHELLHUB_AUTO_SSL=true. If you terminate TLS somewhere else, you are
publishing HTTP and your proxy is doing the rest.

SSH does not go through the gateway. The SSH port is published by the server process
directly. The gateway handles web traffic only. If you are putting a load balancer in front of
ShellHub, the SSH port needs its own path — it is not HTTP and it will not survive an HTTP proxy.

Behind a load balancer Copy Chapter

A Layer 4 load balancer can pass the client address in a PROXY protocol header. The gateway and
the SSH port read that header under separate settings.

For web traffic, set SHELLHUB_PROXY=true on the gateway. SHELLHUB_PROXY_TRUSTED_IPS decides
which peers are allowed to declare a client address. It defaults to 0.0.0.0/0 ::/0, which
trusts everyone. That is fine when nothing but your balancer can reach the port, and wrong if
that is not true.

For SSH, set SHELLHUB_SSH_PROXY_TRUSTED_IPS to the space-separated ranges the header arrives
from, such as your balancer's or your ingress pods'. The SSH port always trusts loopback and
nothing else by default. It closes a connection whose header comes from any other peer, and logs
a warning with that peer's address. Under Docker Compose, do not list the Docker bridge range:
every external client appears to come from it.

This matters beyond cosmetics: access policy source IPs, firewall rules and the session audit trail
read the client address of SSH and web terminal sessions, and password lockout reads it at web
sign-in. Get it wrong and all of them operate on the balancer's address.

If you terminate TLS at a reverse proxy that speaks HTTP — nginx, Caddy, Traefik — you do not
need SHELLHUB_PROXY.

TLS Copy Chapter

Three ways to get a certificate:

Automatic. Set SHELLHUB_AUTO_SSL=true and SHELLHUB_DOMAIN to a name that resolves to the
server. Certificates are obtained from Let's Encrypt and renewed for you. This requires the
server to be reachable for the challenge.

Your own certificate. Set SHELLHUB_TLS_CERT_FILE and SHELLHUB_TLS_KEY_FILE to paths
inside the gateway container. Set both — with only one, the gateway will not start.

Terminate elsewhere. Leave auto-SSL off, publish HTTP, and let your existing proxy or load
balancer hold the certificate.

SHELLHUB_ACME_CA_SERVER points at a different ACME directory if you are using an internal CA.
Empty means Let's Encrypt production.

Where to go next Copy Chapter

• Environment Variables — Every variable, with defaults.
• Self-Hosting Quickstart — Bring a server up.
• Device Not Appearing — When the agent cannot get through.

Ui Apps Docs Src Pages About Self Hosted Vs Cloud (`ui/apps/docs/src/pages/about/self-hosted-vs-cloud.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Self-Hosted vs. Cloud Copy Chapter

import EditionBanner from "../../components/EditionBanner.astro";

Self-Hosted vs. Cloud-Hosted ShellHub

ShellHub can be used in two ways: self-hosted and cloud-hosted. The self-hosted version runs on
your own servers, from the same source that is on GitHub. The cloud-hosted version is hosted by
us at cloud.shellhub.io.

This page is the short answer to what differs.

What self-hosting actually means Copy Chapter

We built ShellHub to remove work, not add it. The whole point is that an admin stops arranging
public addresses, opening ports, maintaining a jump host and chasing SSH keys across machines,
and instead installs one agent and gets on with the job. As is usually the case with things that
feel simple from the outside, a fair amount happens behind them.

Self-hosting means you own all of it. A ShellHub server is not one process: there is a gateway
terminating TLS, a server process carrying both the API and the SSH endpoint, a web console, a
PostgreSQL database holding everything that matters, and a cache and task queue. You are
responsible for keeping those running, for the certificates, for the backups, and for being the
person who gets paged when a fleet cannot connect.

Two things make that easier than it sounds. It is a small stack — four services plus the
database — brought up with a single make start, and every variable it reads is documented in
Environment Variables.

Two things make it harder. The server has to be reachable, unlike your devices, so you need
somewhere with a stable public address. And you inherit the database: PostgreSQL holds your
devices, identities and policies, and nothing backs it up for you.

If you are running a homelab, an air-gapped network, or you have a compliance requirement that
rules out someone else holding your data, self-hosting is the right answer and the docs will get
you there. If you want to reach some devices and would rather not think about any of the above,
Cloud is the right answer and there is no shame in it.

Read How ShellHub Works before deciding — it is a short page and it
explains what you would be operating.

Installation and Maintenance Copy Chapter

Self-hosted, you install and maintain every component, and you back up and secure the data. The
Self-Hosting Quickstart gets a working server up in a few commands; the
ongoing part is yours.

Cloud-hosted, you install the agent on your devices and log in. That is the entire operational
burden. Updates, certificates, database, and availability are ours.

In both cases the agent side is identical — the same binary, the same install command, the same
configuration.

Features Copy Chapter

The two share the whole core: the web terminal, native SSH from any client, file transfer, port
forwarding, container access, tags, roles, API keys, the MCP server, and the full identity-based
access model with SSH identities, access policies and SSH access for API keys. None of that is held
back.

What Cloud adds is the set of things that either need infrastructure we run or only make sense
for an organization paying for a service:

• Multi-factor authentication on user login.
• Server-side session recording, stored centrally rather than in
  the browser that opened the session.
• Web endpoints, publishing an HTTP service from a device at a URL.
• Firewall rules, the legacy restriction layer.
• Multiple namespaces in one account. Community is limited to one.
• Password recovery and email confirmation, which need mail infrastructure.

The Cloud free plan is limited to 3 devices. Self-hosted Community has no device limit.

Where Your Data Lives Copy Chapter

Self-hosted, everything is in your PostgreSQL instance. Nothing leaves your infrastructure.

Cloud-hosted, it is on ours.

This is usually the deciding factor for regulated environments, and it is a legitimate one.

Availability Copy Chapter

Cloud runs with the redundancy you would expect from a service. Self-hosted, availability is
whatever you build: a single Docker Compose deployment on one host is a single point of failure,
and if that host is down, your fleet is unreachable until it comes back.

Devices survive the outage — the agent retries with backoff and reconnects on its own — but
nobody is opening a terminal in the meantime.

Quick Comparison Copy Chapter

Self-hosting means running Community, so that is the column.

Get Started Copy Chapter

• Self-Hosting Quickstart — Bring a server up.
• Editions — What each edition includes, feature by feature.
• Star the project on GitHub.

Ui Apps Docs Src Pages About Shellhub Vs Jump Hosts (`ui/apps/docs/src/pages/about/shellhub-vs-jump-hosts.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: ShellHub vs. Jump Hosts and VPNs Copy Chapter

ShellHub vs. Jump Hosts and VPNs

If you already reach your devices somehow, it is worth being precise about what changes. This
page compares ShellHub to the three things it usually replaces.

The jump host Copy Chapter

A bastion is a machine with a public address that you SSH into first, and from there you SSH
onward to whatever you actually wanted. It is the oldest answer and it still works.

What it costs you: the bastion is a public inbound surface you have to keep patched, the target
machines still have to be reachable from the bastion, so you are still arranging network for
them, and access is expressed as SSH keys sitting in authorized_keys files across the fleet. To
remove one person you go find their key everywhere it landed. The audit trail says which key was
used, not who used it.

What ShellHub does differently: the target devices dial out, so there is nothing to arrange for
them and no second hop. Access is a policy naming a person, evaluated centrally at connection
time. Removing someone is one revocation, in one place.

What a bastion still does better: it is one box and it is yours. If your requirement is "as few
moving parts as possible and nothing phones home", a bastion is honestly hard to beat.

The VPN Copy Chapter

A VPN puts your machine and the target on the same network, and then you connect as if you were
local.

What it costs you: the VPN concentrator is infrastructure to run and a public inbound surface of
its own. Client configuration drifts, and it breaks when networks change. Most importantly, being
on the VPN usually means being able to reach a lot more than the one machine you needed — the
grant is network-shaped, not access-shaped.

What ShellHub does differently: nothing joins a network. A device is a destination, not a
participant, so reaching one device grants nothing about any other. Access is per device and per
unix login, not per subnet.

What a VPN still does better: arbitrary protocols to arbitrary hosts, including things ShellHub
does not carry, and access to devices that cannot run an agent at all.

The mesh network Copy Chapter

A mesh — WireGuard-based overlays and similar — gives every machine an address on a private
network and lets them talk to each other directly, usually peer to peer.

What it costs you: every peer is on the overlay, so a compromised laptop is adjacent to
everything else on it. Containing that is what posture checks and network policies exist for, and
those are real work to configure and keep correct.

What ShellHub does differently: there is no overlay and no peer-to-peer. Devices connect to the
server and nowhere else, so devices cannot reach each other through ShellHub at all. There is no
lateral movement to contain because there is no path between two devices to move along.

What a mesh still does better: machine-to-machine traffic, low latency by going direct, and
anything that genuinely needs an IP-level network rather than access to a specific device.

Choosing Copy Chapter

They are not exclusive. Plenty of people run a mesh for their internal systems and ShellHub for
the fleet in the field, because the two problems are genuinely different.

Where to go next Copy Chapter

• How ShellHub Works — The mechanism behind the middle column.
• How Authorization Works — What replaces the keys in files.

Ui Apps Docs Src Pages Api Ansible (`ui/apps/docs/src/pages/api/ansible.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Ansible Copy Chapter

import Callout from "../../components/Callout.astro";

Ansible

ShellHub ships an Ansible collection, shellhub.core, whose dynamic inventory plugin lists the
devices in a namespace and connects to each one through the gateway. Ansible treats them like any
other SSH host.

Installing the collection Copy Chapter

$ git clone https://github.com/shellhub-io/ansible-collection.git
$ ansible-galaxy collection install ./ansible-collection

The inventory Copy Chapter

The source file's name must end in shellhub.yml, which is how Ansible knows to hand it to the
plugin:

# inventory.shellhub.yml
plugin: shellhub.core.devices
api_url: https://cloud.shellhub.io
ssh_user: root
ssh_key: ~/.ssh/id_ed25519
keyed_groups:
  - key: shellhub_tags
    prefix: tag

The plugin authenticates with a namespace API key, which also tells the server
which namespace to list. Pass it in the environment rather than the file:

$ export SHELLHUB_API_KEY=...
$ ansible-inventory -i inventory.shellhub.yml --graph
$ ansible -i inventory.shellhub.yml tag_production -m ping

Every option can come from the file or the environment:

What it puts in the inventory Copy Section

Only accepted devices, paged through the API. For each one:

ansible_host being identical for every host is the whole point: one inventory reaches machines
on networks that have no route to each other, and the device is identified entirely by
ansible_user.

Because tags arrive as host facts, a device tagged production lands in the tag_production
group with the keyed_groups above — and a device tagged after the fact joins on the next run,
with no inventory to edit. See Tags.

Authentication Copy Chapter

Ansible presents an SSH key like any client, and that key must be an
SSH identity.

Add the key ahead of time. If it is not already an identity, the first connection parks
waiting for somebody to approve it in the console — which for a playbook run means it hangs.
Nobody is watching for that prompt at 3am.

For scheduled runs, connect as an API key with its own SSH access rather than as
a person. The run is then attributed to ansible-runner in the session list, and it does not
break when somebody leaves.

Authorization Copy Chapter

Every host in the play is authorized separately, as its own connection. A play across fifty
devices is fifty authorizations.

So the policy needs to cover the whole set — usually a policy granting the API key a tag,
with the unix login the playbook uses:

A device the policy misses fails in the play as unreachable, which is the correct behavior and
looks like a network problem. If a subset of hosts fails, check the policy before the network.

Performance Copy Chapter

Every connection goes through the ShellHub server, so a play against a large fleet has a different
shape to one on a LAN. Pipelining helps by reducing round trips:

[ssh_connection]
pipelining = True

ControlMaster also works — see SSH Client Configuration — but note that
a persisted connection is authorized once, when it opens.

Where to go next Copy Chapter

• SSH Access — The right principal for a runner.
• SSH Client Configuration — Aliases and multiplexing.

Ui Apps Docs Src Pages Api Ci Cd (`ui/apps/docs/src/pages/api/ci-cd.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: CI/CD Pipelines Copy Chapter

CI/CD Pipelines

A pipeline reaching devices through ShellHub is an SSH client like any other. What makes it worth
its own page is the credential question — get that wrong and the pipeline either breaks
unpredictably or is over-privileged.

Set it up correctly, once Copy Chapter

1. Give the pipeline its own key. Not a person's. Create an API key named for the pipeline,
ci-deploy, then open its SSH access on the Team page and add an SSH key for it.

Two things this buys you: the session list attributes deploys to ci-deploy rather than to
whoever set it up, and the pipeline does not break the week that person leaves. See
SSH Access.

2. Add the key ahead of time. A key that is not yet an identity parks the login waiting for a
browser approval. In a pipeline that is a hang, then a timeout, on a job nobody is watching.

3. Write a policy for it. An all-members allow does not cover an automation, which is
not a member:

Grant the unix login it actually needs. If the deploy runs as deploy, do not grant root.

4. Put the private key in the pipeline's secret store. Nowhere else.

Using it Copy Chapter

GitHub Actions:

- name: Deploy
  env:
    SSH_KEY: ${{ secrets.SHELLHUB_DEPLOY_KEY }}
  run: |
    install -m 600 /dev/stdin ~/.ssh/id_ed25519 <<< "$SSH_KEY"
    ssh -o StrictHostKeyChecking=accept-new \
      [email protected]@cloud.shellhub.io \
      'systemctl restart myservice'

GitLab CI:

deploy:
  script:
    - install -m 600 /dev/stdin ~/.ssh/id_ed25519 <<< "$SHELLHUB_DEPLOY_KEY"
    - ssh -o StrictHostKeyChecking=accept-new
        [email protected]@cloud.shellhub.io
        'systemctl restart myservice'

StrictHostKeyChecking=accept-new accepts the ShellHub server's host key on first use. Pinning it
properly is better if your runner has persistent state — and be aware that regenerating the
server's SSH host key changes it.

Deploying to a fleet Copy Chapter

Do not enumerate devices in the pipeline. Query them by tag and iterate, so a device added next
month is included without an edit:

$ curl -s -H "X-API-Key: $SHELLHUB_API_KEY" \
    "https://cloud.shellhub.io/api/devices" | \
  jq -r '.[] | select(.tags[]?.name == "production") | .name' | \
  while read -r device; do
    ssh "deploy@[email protected]" 'systemctl restart myservice'
  done

That needs both credentials, and they are different things: an
API key to list devices over HTTP, and the SSH key that key owns to
connect. Neither substitutes for the other, though both belong to the same principal.

For anything beyond a loop, use Ansible.

Short-lived credentials Copy Chapter

For a genuinely one-shot job — a provisioning run, a migration — an automation's key can be
single use: spent after one connection. Combined with an expiry, that is the tightest
credential available.

What to watch for Copy Chapter

A device the policy misses fails as unreachable, which looks like a network problem. Check the
policy before the network.

Ephemeral runners each connect fresh, so the key must already be an identity — a runner cannot
complete a browser approval.

Sessions are attributed and recorded like any other. If recording is on, pipeline sessions are
recorded too.

Where to go next Copy Chapter

• SSH Access — The principal a pipeline should hold.
• Ansible — Beyond a shell loop.
• Provisioning Keys — Enrolling what the pipeline creates.

Ui Apps Docs Src Pages Api Ci Debug (`ui/apps/docs/src/pages/api/ci-debug.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Debugging a CI Run Copy Chapter

import Callout from "../../components/Callout.astro";

Debugging a CI Run

A build that only fails in CI is the worst kind. ShellHub ships a GitHub Action that registers
the runner itself as a device, so you open a shell on the machine while the job is still standing.

The action installs the agent on the runner, registers it as an ephemeral device, accepts it, and
removes it when the job ends. The session goes through your own gateway, which is what separates
this from pasting a tunnel URL into a public log: access is governed by your namespace, the key
is one you manage, and the session is recorded.

The action authorizes you with a public key, which a new namespace does not consult, so it works
in a legacy namespace only.

The step Copy Chapter

- uses: shellhub-io/ci-action@v1
  with:
    server: https://cloud.shellhub.io
    tenant-id: ${{ secrets.SHELLHUB_TENANT_ID }}
    api-key: ${{ secrets.SHELLHUB_API_KEY }}

The job log prints an ssh command and a browser URL. The browser URL opens the runner's terminal
in the console, so you do not need a client at all.

The runner needs Docker, which the GitHub-hosted ubuntu-* images have. The API key needs
permission to accept and remove devices, and to remove public keys when the action manages one for
you.

Only when something broke Copy Chapter

Waiting on every green build is not the point. Gate the step:

- name: build
  run: make
- uses: shellhub-io/ci-action@v1
  if: failure()
  with:
    server: https://cloud.shellhub.io
    tenant-id: ${{ secrets.SHELLHUB_TENANT_ID }}
    api-key: ${{ secrets.SHELLHUB_API_KEY }}
    timeout: 1800

Blocking or detached Copy Chapter

By default the step blocks: the job stops there and waits for you. Once you connect it holds
until you disconnect, and sudo touch /continue inside the session releases it early. Connection
state is read from the runner's /dev/pts, so it releases a few seconds after a dropped
connection rather than hanging on it.

detached: true inverts that — the job carries on and the runner stays reachable, with
idle-timeout deciding how long the teardown waits at the end for somebody to connect.

Authorizing yourself Copy Chapter

Your public key has to be authorized in ShellHub, scoped to the device's tags — github unless
you set tags. Three ways, and they differ in what is left behind:

authorize-actor: true requires the actor to have keys and warns when they have none; auto is
best effort and stays quiet.

Which user you land as Copy Chapter

The agent runs as root with host access, so the shell is on the runner itself rather than in a
container, and you can connect as any user on it:

ssh <user>@<namespace>.ci-<run_id>-<attempt>@cloud.shellhub.io

ssh-username pins one user — it is a regular expression, defaulting to .* — and the pinned
name is filled into the command the action prints.

Where to go next Copy Chapter

• CI/CD Pipelines — The other direction: a pipeline reaching your devices.
• API keys — What the action authenticates with.
• Tags — What scopes the access.

Ui Apps Docs Src Pages Api Mcp (`ui/apps/docs/src/pages/api/mcp.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: MCP Server Copy Chapter

MCP Server

ShellHub ships a Model Context Protocol server, so an AI assistant can work with your namespace
directly — list devices, look at sessions, and act on them — instead of you relaying output into a
chat window.

It is mounted at /mcp as an MCP Streamable HTTP server.

The MCP server is in Community and is registered unconditionally, on every edition.

Connecting Copy Chapter

Point an MCP-capable client at your server's /mcp endpoint and give it an API key.

https://cloud.shellhub.io/mcp

Authentication is API-key only Copy Chapter

This is the part to understand before wiring anything up.

MCP authenticates with an API key and nothing else. The user-identity headers that the rest of
the API accepts do not apply here and are deliberately omitted. There is no way to connect an
assistant "as yourself" with your session — it connects as an API key.

The consequence: the assistant can do whatever the key's role can do. Give it an observer key
if it should look and not touch. Give it an operator key only if you have decided you want it
acting.

See API keys and User Roles.

How authorization is enforced Copy Chapter

The MCP tools make in-process API calls, replaying the captured authentication headers. That means
the same middleware the HTTP API uses runs for an MCP request: the same permission checks, the
same tenant scoping, and the same refusals for routes that block API keys.

So an assistant cannot reach anything through MCP that the key could not reach through the HTTP
API. There is no separate, looser path — which is exactly the property you want from a tool an
assistant drives.

The routes that refuse API keys refuse MCP too. See
What a key cannot do.

What it exposes Copy Chapter

Tools covering the namespace's resources — devices among them. The set grows with releases; ask
your client to enumerate the available tools, since MCP is self-describing.

Being deliberate about it Copy Chapter

An assistant with an operator key can change things in your namespace. That is the point, and it
is worth a moment's thought:

• Start with an observer key. Most of the value is in asking questions.
• Use a separate key for the assistant, named for it, so you can revoke it without touching
  anything else.
• Give it an expiry.
• The key is in your assistant's configuration. Treat that file as holding a credential.

Where to go next Copy Chapter

• API keys — Creating a scoped key.
• API Authentication — The underlying model.

Ui Apps Docs Src Pages Api Provisioning Key Webhook (`ui/apps/docs/src/pages/api/provisioning-key-webhook.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Provisioning Key Webhook Copy Chapter

import Callout from "../../components/Callout.astro";

Provisioning Key Webhook

A provisioning key in webhook mode asks your service whether to admit
each device that enrolls with it. This page is the contract: what ShellHub sends, what it accepts
back, and how to answer later instead of immediately.

The request Copy Chapter

ShellHub sends a POST with a JSON body and two headers.

{
  "tenant_id": "00000000-0000-4000-0000-000000000000",
  "provisioning_key_id": "b1946ac92492d2347c6235b4d2611184",
  "provisioning_key_name": "factory-line-2",
  "device_uid": "3c9e2f1a7b4d8e6f0a1c5d9b2e7f4a83",
  "identity": "00:1b:44:11:3a:b7",
  "hostname": "gateway-01",
  "info": { "id": "debian", "pretty_name": "Debian GNU/Linux 12", "arch": "arm64" },
  "source_ip": "203.0.113.9",
  "timestamp": "2026-08-26T03:41:00Z",
  "callback_url": "https://cloud.shellhub.io/api/devices/enroll/callback/<token>"
}

The secret itself is never sent, not even a fragment. Authenticity comes from the signature:
compute the same HMAC over the raw body you received and compare.

callback_url is absent when the server cannot work out its own public address.

The answer Copy Chapter

Reply 2xx with a JSON body:

{ "decision": "accept", "reason": "serial in manufacturing batch 44" }

reason is optional and is recorded with the decision.

Anything else fails closed to pending: a transport error, a non-2xx status, a body that does
not parse, an unrecognized decision, or no answer inside the timeout. The device waits for a
human rather than walking in.

The request times out in 5 seconds by default, 15 at most. Answer defer rather than
holding the connection open.

Deciding later Copy Chapter

POST to the callback_url from the request:

$ curl -X POST "$CALLBACK_URL" \
    -H 'Content-Type: application/json' \
    -d '{"decision":"accept"}'

Only accept and reject are valid here — defer has already happened.

The URL carries a signed, expiring token scoped to that one device. It is valid for 1 hour by
default, 24 hours at most, and it is single use: a second POST with the same URL is
refused, so a replay cannot flip a decision.

An accept arriving through the callback is checked again on the way in. The key is re-resolved
and revalidated, because it may have been revoked, disabled, expired or exhausted since the token
was minted, and a use is reserved against its limit. A deferred accept is bound by the same rules
as an immediate one.

A device left pending this way is re-evaluated the next time the agent authenticates, so a
decision that was deferred resolves on its own once your service answers.

Reachability Copy Chapter

The webhook must be reachable at a public address. The destination is checked after DNS
resolution, so a hostname that resolves into a private network is refused too.

Where to go next Copy Chapter

• Provisioning Keys — The modes, and everything a key carries.
• API Authentication — The credentials the rest of the API takes.

Ui Apps Docs Src Pages Api Ssh Access (`ui/apps/docs/src/pages/api/ssh-access.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: SSH Access Copy Chapter

SSH Access

An automation reaches devices as an API key. The key's token never opens an SSH session, and an SSH
identity never calls the API. Over SSH the API key connects as its own principal, with a public key
enrolled for it. An access policy naming the API key decides where it may reach.

Enrolling the key's SSH key Copy Chapter

Enrolling needs permission to manage SSH identities, which an administrator and an owner hold.
Permission to add your own key is not enough. Without permission to manage them, the SSH
access column on Team → API Keys shows only a dash.

The column shows how many SSH keys each API key holds, or Not set up when it holds none. Open
the key's cell and choose Add SSH key, or Add once it holds one. Paste the public key the
automation will connect with.

A key's credentials live with the key. The SSH Identities page is about people and never lists
them.

Naming the key in a policy Copy Chapter

A key holds no membership and no role over SSH, so an all-members allow never covers it, and
neither does a role subject. An all-members deny does not cover it either, so a namespace-wide
"no root anywhere" has to name the key too.

Policy Reference has the full subject rules.

Limiting the key's lifetime Copy Chapter

Give the SSH key an expiry, so an automation nobody touched in a year does not still hold live
credentials. For a one-shot job, a provisioning run or a migration, make it single use, so
it authorizes one session and is then consumed.

Deleting the API key removes the SSH identities it owns and the policies naming it. An expired API
key opens nothing, even while its SSH key is still enrolled.

No re-authentication Copy Chapter

A policy's require_reauth never applies to an API key. Re-auth is an interactive browser step
and there is nobody to complete it, so demanding one would hang the connection. Freshness comes
from the key's expiry and single use instead. If a path needs re-auth, it needs a person on it.

Where to go next Copy Chapter

• API keys — Creating the key itself, and what it may do over HTTP.
• Access Policies — Granting the key something.
• CI/CD Pipelines — A pipeline set up this way, end to end.

Ui Apps Docs Src Pages Api Terraform (`ui/apps/docs/src/pages/api/terraform.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Terraform Copy Chapter

import Callout from "../../components/Callout.astro";

Terraform

Two different things people mean by "Terraform and ShellHub", and they are worth separating.

Reaching a device from a provisioner Copy Chapter

Terraform's remote-exec and file provisioners connect over SSH, and ShellHub's SSHID is an
ordinary SSH username:

connection {
  type        = "ssh"
  host        = "cloud.shellhub.io"
  user        = "[email protected]"
  private_key = file("~/.ssh/id_ed25519")
}

provisioner "remote-exec" {
  inline = [
    "systemctl restart myservice",
  ]
}

The host is always the ShellHub server; the device is identified by user.

The key must already be enrolled. If it is not, the connection parks waiting for a browser
approval and Terraform hangs until it times out. Enroll it ahead of time through the API key's
SSH access.

Managing ShellHub itself Copy Chapter

ShellHub's HTTP API is what you would target to manage devices, tags or access policies as code.
An API key cannot create a namespace or manage API keys, so those stay a person's job in the
console. See What a key cannot do.

There is no official ShellHub Terraform provider. The options are the generic HTTP provider for
simple cases, or null_resource with a local-exec calling the API:

resource "null_resource" "shellhub_tag" {
  provisioner "local-exec" {
    command = <<-EOT
      curl -sf -X POST https://cloud.shellhub.io/api/... \
        -H "X-API-Key: ${var.shellhub_api_key}" \
        -H "Content-Type: application/json" \
        -d '{ ... }'
    EOT
  }
}

Be honest with yourself about that pattern: it has no real state tracking, no drift detection and
no meaningful destroy. For anything beyond a couple of resources, a script against the API is
clearer than pretending it is declarative.

See API Authentication and the
the specification for the endpoints.

Enrolling devices Terraform creates Copy Chapter

If Terraform is creating machines that should appear in ShellHub, put the agent in at creation
with a provisioning key, through cloud-init or user data:

user_data = <<-EOT
  #!/bin/sh
  curl -sSf https://cloud.shellhub.io/install.sh | \
    PROVISIONING_KEY=${var.shellhub_provisioning_key} \
    sh
EOT

A provisioning key in automatic mode means instances arrive accepted and tagged, with nobody
watching a console. That is the pattern worth adopting — it is the one that scales.

Where to go next Copy Chapter

• Provisioning Keys — Automatic enrollment.
• Ansible — Usually the better tool for configuring a device.

Ui Apps Docs Src Pages Connect Container Access (`ui/apps/docs/src/pages/connect/container-access.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Container Access Copy Chapter

import Shot from '../../components/Shot.astro';

Container Access

The Connector exposes containers running on a host as ShellHub devices in their own right. Each
container gets its own entry, its own SSHID, and its own place in your access policies.

What it changes Copy Chapter

Without it, you reach a container by SSHing to the host and then docker exec-ing in — which
means everyone who needs a container needs the host, and the host is a much larger grant.

With it, the container is a device. You can write a policy that grants somebody a container and
not the machine underneath it.

Setting it up Copy Chapter

From the console's Containers page, click Add Docker Host:

<Shot id="add-docker-host" route="/containers" of={{ role: "dialog" }} before={[{ click: { role: "button", name: "Add Docker Host" } }]} alt="ShellHub Containers page with the Add Docker Host dialog open" />

In a new namespace the dialog sends you to Fleet. Open a provisioning key there and pick its
Docker connector method: the one-line command it shows enrolls every container with that key.
In a legacy namespace the dialog gives you the
one-line command with the namespace's tenant ID.

Run the command on the host. The Connector then watches the Docker daemon and registers containers
as they appear.

Configuration Copy Chapter

The Connector takes its own variables, which differ from the agent's in one important way:

SHELLHUB_PRIVATE_KEYS being a directory follows from each container being a separate device:
separate devices need separate identities. Put that directory on a volume — if the keys are lost,
every container comes back as a new device.

SHELLHUB_CONNECTOR_LABEL is how you avoid registering every container on a busy host. Set it,
label the containers you actually want reachable, and the rest are ignored.

Connecting Copy Chapter

A registered container behaves like any device:

$ ssh [email protected]@cloud.shellhub.io

Authentication inside a container Copy Chapter

Containers usually have no real user accounts, and this is where it gets awkward.

With the Connector enabled, password authentication is refused for a user with no password set in
the container's /etc/shadow — which is most container users. Two ways forward: set one with
passwd inside the container, or use public-key authentication, which works regardless.

Public keys are the better answer in every case where you have a choice.

Availability Copy Chapter

Container access is in Community. It is switched on by SHELLHUB_CONNECTOR, which defaults to
true.

Lifecycle Copy Chapter

Containers come and go, and a device list that accumulates one entry per container that ever
existed becomes unusable. Prune stopped containers' entries, and consider whether the containers
you actually need reachable are a small labelled subset — which is what SHELLHUB_CONNECTOR_LABEL
is for.

Where to go next Copy Chapter

• Access Policies — Granting a container and not its host.
• Tags — Selecting containers as a group.

Ui Apps Docs Src Pages Connect File Transfer (`ui/apps/docs/src/pages/connect/file-transfer.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: File Transfer Copy Chapter

File Transfer

scp and sftp work through ShellHub with no special handling. The agent serves SFTP over the
same connection that carries a shell.

scp Copy Chapter

$ scp firmware.bin [email protected]@cloud.shellhub.io:/tmp/

And back:

$ scp [email protected]@cloud.shellhub.io:/var/log/syslog ./

sftp Copy Chapter

For an interactive session:

$ sftp [email protected]@cloud.shellhub.io
sftp> cd /var/log
sftp> get syslog
sftp> put patch.tar.gz /tmp/
sftp> quit

Any SFTP client works — FileZilla, WinSCP, Cyberduck, your editor's remote support. Point them at
the server as the host and the SSHID as the username.

rsync Copy Chapter

rsync runs over SSH, so it works too, and is what you want for anything large or repeated:

$ rsync -avz ./build/ [email protected]@cloud.shellhub.io:/opt/app/

The -z matters more here than on a LAN — the path goes out to the server and back down to the
device.

Permissions Copy Chapter

Transfers happen as the unix user in the SSHID, with exactly that user's permissions. If you
cannot write to /opt as deploy, ShellHub will not help — that is the device's decision, not
ShellHub's.

Which unix users you may connect as is decided by access policies. A policy granting only
deploy means you transfer as deploy and nothing else, even on a device where root exists.
See Access Policies.

What recording does and does not capture Copy Chapter

Session recording captures the terminal — what was typed and what was displayed. File transfer
payloads are not recorded. A recording will show that somebody was connected; it will not show
you the bytes of a file they copied.

If that gap matters for your audit requirements, know about it now rather than during an incident.
See what a recording holds.

Large transfers Copy Chapter

Everything goes through the server, so a multi-gigabyte transfer occupies that path for its
duration. For images and firmware being pushed to many devices, a release artifact somewhere the
devices can fetch from — and a shell command to fetch it — is usually kinder than pushing the same
bytes through the gateway once per device.

Where to go next Copy Chapter

• Connecting to a Device — The SSHID this all relies on.
• Port Forwarding — Reaching a service instead of a file.
• SSH Client Configuration — Aliases, if the full address gets tedious.

Ui Apps Docs Src Pages Connect Port Forwarding (`ui/apps/docs/src/pages/connect/port-forwarding.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Port Forwarding Copy Chapter

import Callout from "../../components/Callout.astro";

Port Forwarding

Port forwarding is what turns "I can get a shell" into "I can reach the thing that shell can
reach". Standard SSH local forwarding works through ShellHub.

Reaching a service on the device Copy Chapter

A database bound to localhost on the device, reachable at localhost:5432 on your machine:

$ ssh -L 5432:localhost:5432 [email protected]@cloud.shellhub.io

Then connect your client to localhost:5432 as usual. The service does not need to be listening
on anything but loopback — the agent is on the device, so loopback is local to it.

That is the common case and it is genuinely useful: a web admin interface, a database, a metrics
endpoint, all of them bound to 127.0.0.1 on a device you cannot otherwise reach.

Reaching something else on the device's network Copy Chapter

The forward target is resolved by the device, so it does not have to be the device itself:

$ ssh -L 8080:192.168.1.50:80 [email protected]@cloud.shellhub.io

Now localhost:8080 on your machine reaches a web interface on 192.168.1.50 — a PLC, a camera,
a switch — on a LAN that has no route to you at all.

This is worth dwelling on, because it is the widest thing ShellHub does. One device with an agent
becomes a way in to everything that device can see. A device on a factory network is a way to
reach the factory network.

Keeping the forward without a shell Copy Chapter

-N opens the forward and no terminal:

$ ssh -N -L 5432:localhost:5432 [email protected]@cloud.shellhub.io

Add -f to background it. To close it, kill the process — or use a control socket, which is
tidier:

$ ssh -M -S ~/.ssh/cm-pi -fNT -L 5432:localhost:5432 pi
$ ssh -S ~/.ssh/cm-pi -O exit pi

Several at once Copy Chapter

Repeat -L:

$ ssh -N \
    -L 5432:localhost:5432 \
    -L 8080:localhost:80 \
    -L 9090:localhost:9090 \
    pi

Reverse forwarding is refused Copy Chapter

ssh -R does not work. The server declines every reverse forwarding request, and there is no
setting that enables it. To reach a service on the device from outside, publish a
web endpoint instead.

Authorization Copy Chapter

A forward rides on a session, so it is governed by whatever authorized that session. Policies
grant a device and a set of unix logins; there is no separate per-port permission.

The practical consequence: granting somebody shell on a device grants them forwarding from it
too. If you need someone to reach one service and nothing else, ShellHub's port forwarding is not
the mechanism — a web endpoint is closer, since it publishes exactly
one service.

Authorization is checked when the session is established. A long-lived -N forward was authorized
once, at the start, and revoking access does not tear it down. See
How Authorization Works.

Where to go next Copy Chapter

• Web Endpoints — Publishing one HTTP service at a URL instead.

Ui Apps Docs Src Pages Connect Ssh Clients (`ui/apps/docs/src/pages/connect/ssh-clients.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: SSH Client Configuration Copy Chapter

SSH Client Configuration

An SSHID is correct but long. Nothing here changes how ShellHub works — it is about typing less.

OpenSSH Copy Chapter

Add an entry to ~/.ssh/config:

Host pi
  HostName cloud.shellhub.io
  User [email protected]

Then:

$ ssh pi

The whole SSHID goes in User, and HostName is just the server. That split is what makes the
rest of the OpenSSH ecosystem work — scp, sftp, rsync and anything reading ssh_config all
honor the alias.

For a fleet, a wildcard saves writing one block per device:

Host *.shellhub
  HostName cloud.shellhub.io
  User root@mycompany.%h

That is imperfect — %h includes the .shellhub suffix — so most people end up with explicit
blocks for the devices they touch often and the full SSHID for the rest.

Keys Copy Chapter

Point at a specific key the normal way:

Host pi
  HostName cloud.shellhub.io
  User [email protected]
  IdentityFile ~/.ssh/id_ed25519
  IdentitiesOnly yes

IdentitiesOnly yes is worth setting. Without it, OpenSSH offers every key it has, and the
first one ShellHub recognizes is the identity your session is attributed to — which may not be
the one you meant.

PuTTY Copy Chapter

Put the SSHID in Host Name as [email protected]@server, or set the server as the host
and the SSHID's user part under Connection → Data → Auto-login username.

Save it as a session so you do not retype it.

Ansible Copy Chapter

The SSHID goes in the inventory as the connection user:

[edge]
raspberrypi ansible_host=cloud.shellhub.io [email protected]

Or in YAML:

all:
  hosts:
    raspberrypi:
      ansible_host: cloud.shellhub.io
      ansible_user: [email protected]

See Ansible for generating the inventory from your device list rather than
maintaining it by hand.

rsync, scp and sftp Copy Chapter

They inherit ~/.ssh/config, so an alias covers them:

$ scp file.tar.gz pi:/tmp/
$ rsync -av ./build/ pi:/opt/app/

Without an alias, quote carefully — the SSHID contains @ twice:

$ scp file.tar.gz [email protected]@cloud.shellhub.io:/tmp/

See File Transfer.

Multiplexing Copy Chapter

Reusing one connection for several sessions makes repeated commands noticeably faster:

Host pi
  HostName cloud.shellhub.io
  User [email protected]
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 10m

Be aware of the interaction with authorization: ShellHub authorizes when the connection is made.
A multiplexed connection held open for ten minutes was authorized once, at the start.

Where to go next Copy Chapter

• File Transfer — Moving files over the same path.
• Port Forwarding — -L and -R through ShellHub.

Ui Apps Docs Src Pages Connect Web Endpoints (`ui/apps/docs/src/pages/connect/web-endpoints.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Web Endpoints Copy Chapter

import EditionBanner from "../../components/EditionBanner.astro";
import Shot from '../../components/Shot.astro';

Web Endpoints

A web endpoint takes an HTTP service running on a device and gives it a URL. Somebody opens the
URL in a browser and reaches the service, with nothing installed and no SSH involved.

What it is for Copy Chapter

A device is running a web interface — a dashboard, an admin panel, a camera's UI — on a network
you cannot reach. A port forward solves that for you, on your
machine, for as long as the forward is open.

A web endpoint solves it for anyone you give the URL to, with no client at all. That is the
difference, and it is the reason to choose one over the other.

Creating one Copy Chapter

From the console's Web Endpoints page, pick the device and the port the service is listening
on. You get back a URL.

<Shot id="web-endpoints" route="/web-endpoints" of={{ role: "main" }} edition="enterprise" alt="The Web Endpoints page listing active endpoints with their public URLs, targets, and time remaining" />

The endpoint carries an expiry, shown in the list as time remaining.

How access works Copy Chapter

This is the part to be clear-eyed about. A web endpoint is reached by knowing its URL. The
address contains a random component that is both its name and its secret. There is no login in
front of it, and access policies do not apply to it.

The consequences:

• Anyone with the URL reaches the service, from anywhere.
• The URL in a chat message, a ticket, or a browser history is a working credential.
• Revoking access means deleting the endpoint, not changing a policy.

That is a reasonable trade for showing somebody a dashboard for an afternoon. It is the wrong
mechanism for standing access to something sensitive — use SSH and policies for that.

Set expiries deliberately, and delete endpoints when the reason for them has passed.

What it does not expose Copy Chapter

Publishing an endpoint publishes one service on one port. It does not give anyone a shell, a
file transfer, or access to anything else on the device. The device itself stays unreachable.

Self-hosted configuration Copy Chapter

On Enterprise, web endpoints need a DNS provider so certificates can be issued for the generated
hostnames:

Endpoints get their own hostnames under the endpoints domain, so that domain needs a wildcard DNS
record pointing at the server.

Where to go next Copy Chapter

• Port Forwarding — The alternative, for yourself rather than others.
• Environment Variables — The self-hosted settings above.

Ui Apps Docs Src Pages Get Started Agent Configuration (`ui/apps/docs/src/pages/get-started/agent-configuration.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Agent Configuration Copy Chapter

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 Copy Chapter

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 Copy Chapter

See How a device enrols for how these interact.

Connection Copy Chapter

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

Identification Copy Chapter

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 Copy Chapter

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

Where to go next Copy Chapter

• Managing Devices — How a device enrols, and what identifies one.
• Device Not Appearing — When configuration is the cause.

Ui Apps Docs Src Pages Get Started Install (`ui/apps/docs/src/pages/get-started/install.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Install the Agent Copy Chapter

import ActionLink from "../../components/ActionLink.astro";
import Callout from "../../components/Callout.astro";

Install the Agent

The agent is what a device runs. It opens one outbound connection to the server and keeps it,
which is what makes the machine reachable without anything listening on it.

$ curl -sSf https://cloud.shellhub.io/install.sh | sh

Install ShellHub

Nothing else is needed. Given no credential the agent pairs: it prints a code, you enter it in the
console, and the device joins the namespace you pick. Quickstart walks that path
end to end.

The script is served by the server it will register with, which writes its own address into it on
the way out — port included. Fetch it from your own server and you get one that registers there.

What the script does Copy Chapter

1. Picks a method by looking at the machine: Docker, then Podman, then Snap, then WSL, then a
   native binary. The first one that works is used.
2. Detects the architecture — amd64, armv6, armv7, arm64, 386.
3. Installs the agent and registers it to start at boot.

Force a method with INSTALL_METHOD when the choice is wrong for you:

$ curl -sSf https://cloud.shellhub.io/install.sh | INSTALL_METHOD=standalone sh

The methods Copy Chapter

Docker Copy Section

Picked when a rootful daemon is usable. Leaves a container running the agent, plus a
shellhub-agent wrapper on the host.

The wrapper is there because shellhub-agent login opens a browser during pairing, which an
agent inside a container cannot do. The container itself runs privileged, with the host's
filesystem and process namespace: the agent opens shells as real unix users and forwards ports on
their behalf, and a confined container can do neither.

$ docker ps | grep shellhub          # is it running
$ docker logs -f <container>         # what it is doing
$ docker restart <container>         # restart it

Podman Copy Section

Picked when Podman is present and rootful. The same image and the same wrapper as Docker.

Rootful is a requirement, not a preference: the installer declines rootless, because an agent
installed that way would appear to work and fail at the moment somebody tried to use it.

$ podman ps | grep shellhub          # is it running
$ podman logs -f <container>         # what it is doing
$ podman restart <container>         # restart it

Snap Copy Section

Picked when the snap command is present. Leaves the shellhub snap. The snap needs the tenant
named up front and cannot pair or take a provisioning key, so its device always lands pending until
somebody accepts it.

That snap is classic rather than strict, for the same reason the containers are privileged,
and classic snaps cannot be installed on Ubuntu Core — run the agent as a container under the
Docker snap there instead. Being a snap also means snapd refreshes it on its own schedule, so
the agent updates itself; sudo snap refresh --hold shellhub pins it.

$ snap services shellhub             # is it running
$ sudo snap logs -f shellhub         # what it is doing
$ sudo snap restart shellhub         # restart it

WSL Copy Section

Picked on WSL 2 with Ubuntu. Leaves a native binary under systemd, inside the distribution.

Each of those is a requirement rather than a description: version 2, Ubuntu, systemd enabled, and
mirrored networking. The installer checks all four and stops on any of them.

$ systemctl status shellhub-agent    # is it running
$ journalctl -u shellhub-agent -f    # what it is doing

Standalone Copy Section

Picked when nothing above matched. Leaves a binary and a systemd unit that starts it at boot.

That unit is the whole of it: no daemon, no container runtime, no snapd, which is what makes this
the leanest way to run the agent.

$ systemctl status shellhub-agent    # is it running
$ journalctl -u shellhub-agent -f    # what it is doing
$ sudo systemctl restart shellhub-agent   # restart it

What it configures Copy Chapter

SERVER_ADDRESS is filled in for you. Set it only to point somewhere other than where the script
came from.

Enrolling without accepting each device Copy Chapter

Pairing asks somebody to approve the device, which is right for the machines in front of you and
wrong for a hundred of them. A provisioning key carries the namespace
and the rule for what happens on arrival, so devices enrol on their own, tagged:

$ curl -sSf https://cloud.shellhub.io/install.sh | PROVISIONING_KEY=<your-provisioning-key> sh

Uninstalling Copy Chapter

$ curl -sSf https://cloud.shellhub.io/install.sh | sh -s uninstall

Standalone, WSL, Docker and Podman are supported. Other methods refuse rather than half-remove
themselves; a Snap install goes with snap remove shellhub.

Machines the script does not cover Copy Chapter

The script assumes a machine that already exists, with somebody — or a provisioning script —
running a command on it. These are not that command with a different flag.

Yocto and Buildroot are embedded build systems: the agent goes into the product image while the
image is built, before there is a machine to run anything on. FreeBSD has its own packaging.
Building from source is you producing the binary.

• Raspberry Pi — A card image that enrols itself on first
  boot.
• Yocto Project — The meta-shellhub OpenEmbedded layer.
• Buildroot — The ShellHub external tree, same idea.
• FreeBSD — The
  ShellHub ports tree.
• Building from Source — For a platform nothing above
  covers, or to run an agent you built yourself.

A unit coming off a line has no console to open and no link to click, so an image carries a
provisioning key rather than waiting to be paired. And the key that identifies a device is generated by
the agent on first start: one baked into an image makes every unit the same device, and one the
unit cannot keep makes it a new device on every boot. See
Agent Configuration for where that file lives.

Where to go next Copy Chapter

• Quickstart — Accept the device and open a terminal on it.
• Agent Configuration — Every agent variable.
• Device Not Appearing — If it never shows up.

Ui Apps Docs Src Pages Help Support (`ui/apps/docs/src/pages/help/support.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Getting Support Copy Chapter

Getting Support

Where to go Copy Chapter

GitHub Issues — bugs and feature requests.
Search first; a lot of things are already there.

GitHub Discussions — questions, and
"is this supposed to work like this".

Cloud and Enterprise customers have their support channel through their account.

Before you ask Copy Chapter

Two pages answer most of what comes up, and checking them first usually saves a round trip:

• Connection Denied — a connection is refused
• Device Not Appearing — a device is missing or offline

What to include Copy Chapter

The difference between a fast answer and three days of clarifying questions:

Which edition and version. Community, Cloud or Enterprise, and the version:

$ grep SHELLHUB_VERSION .env      # self-hosted

Self-hosted or Cloud. They fail differently.

Whether the namespace is legacy. A legacy namespace and a new one authorize SSH differently.
See How Authorization Works.

How the agent was installed. Docker, Podman, standalone, WSL, or built into an image.

What you did, what happened, what you expected. Concretely. "It does not work" cannot be
acted on; "ssh [email protected]@server returns permission denied, and the device shows online in
the console" can.

Logs, if the server is yours:

$ ./bin/docker-compose logs --tail 200

Agent logs, from the device:

$ docker logs <container>
$ journalctl -u shellhub-agent -n 200
$ sudo snap logs shellhub

What not to include Copy Chapter

Redact before pasting:

• The contents of .env.override — it has your database password
• API keys and provisioning keys
• Private keys, always
• Tenant IDs, if you would rather not have them public

Log output can carry addresses and hostnames too. A quick read before pasting is worth it.

Reporting a security issue Copy Chapter

Do not open a public issue. There are two private routes: a
GitHub Security Advisory,
which is the preferred one and is visible only to maintainers, or [email protected]. Receipt
is confirmed within two business days.

ShellHub follows coordinated disclosure, assigns a CVE to every confirmed vulnerability, and
publishes an advisory once a fix exists. The
security policy carries the
patch targets by severity and what an advisory contains.

Contributing a fix Copy Chapter

ShellHub is open source and the fix may well be yours. Open an issue first for anything larger
than a small change, so the discussion happens before the work; for a small one, the pull request
is the discussion. Branch, push, open the PR against the relevant repository.

CONTRIBUTING.md has the
rest, including the code of conduct every interaction is expected to follow, and the repository's
README covers getting the stack running.

Where to go next Copy Chapter

• FAQ — Short answers to common questions.
• Troubleshooting — Self-hosted server problems.

Ui Apps Docs Src Pages Help Troubleshooting (`ui/apps/docs/src/pages/help/troubleshooting.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Troubleshooting Copy Chapter

Troubleshooting

Pick the area closest to what is failing. Every guide below lives beside the feature it covers,
so none of this is a second copy that drifts from the first.

Connecting Copy Chapter

Devices Copy Chapter

Signing in Copy Chapter

Your own server Copy Chapter

Automation Copy Chapter

Still stuck Copy Chapter

Getting Support has where to ask, what to include so the first answer is useful,
and what to redact before pasting.

Ui Apps Docs Src Pages Manage Access Control (`ui/apps/docs/src/pages/manage/access-control.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: How Authorization Works Copy Chapter

How Authorization Works

Every connection is authorized before the device is contacted. ShellHub refuses at the server,
before it mints anything for the agent, so a denied login never reaches the device at all.

How the decision is made depends on which model your namespace uses.

Two models Copy Chapter

Namespaces created today are new and stay that way. Namespaces that predate identities
are legacy, and can be upgraded once, when you are ready; there is no way back.

The rest of this page describes a new namespace. For a legacy one see
Public Keys and
Firewall Rules; to move, see
Upgrading a Legacy Namespace.

Identities prove who Copy Chapter

An SSH identity binds a public key to a principal: a person on your team, or an
API key an automation connects as. The key is the credential; the identity is
who that credential belongs to.

This inversion is what makes everything downstream work. In a legacy namespace a key is the
access: whoever holds it gets in, and the record can only name the key. With identities, a
connection whose key fingerprint resolves to an identity is recognized as that principal, and
policy evaluation, the session record and revocation are all about the person.

See SSH Identities.

Policies decide what Copy Chapter

An identity proves who. A policy decides what they may reach: a subject, a set of devices, a set
of unix logins, and whether the effect is to allow or deny.

See Access Policies for writing them, and
Policy Reference for every field.

How a decision is made Copy Chapter

When a connection arrives, ShellHub resolves the presented key to an identity, then evaluates the
namespace's policies against that identity, the target device, and the requested unix login.

The order:

1. Membership. Not a member of the namespace → refused, before policies are consulted.
2. Every deny. A matching deny refuses, and nothing later overrides it. A deny that cannot be
   evaluated also refuses.
3. Every allow. One match is enough. The strictest re-authentication requirement across all
   matching allows is taken.
4. Nothing matched → refused.

Three properties fall out of that, and they are the ones worth remembering:

Default deny. A device is unreachable until some policy says otherwise. A namespace with no
policies at all refuses every connection — and ShellHub short-circuits that case, refusing
immediately rather than proceeding toward a login that could never be authorized.

Deny wins. Deny is a subtractive blocklist carved out of broad grants, not a base layer.
Default deny already blocks everything a policy does not grant, so deny exists to carve exceptions
out of your allows.

Deny fails closed. If a deny's filter or source IP cannot be evaluated, ShellHub assumes it
applies. An allow that cannot be evaluated is treated as a non-match instead — the asymmetry is
deliberate, and it always errs toward refusing.

Where the network does not fit Copy Chapter

Network position is not part of the decision. There is no "inside": a device on your office LAN
and one on a customer's cellular link are evaluated identically, against the same policies.

A policy can carry a source IP restriction, but it only ever narrows a grant that already
matched. An empty list matches any address, and no source IP ever grants access on its own.

In a new namespace the legacy firewall rules, which match on source IP, hostname and username,
are bypassed entirely. They remain stored and manageable, and are never consulted.

The starter policy Copy Chapter

A new namespace is seeded with one policy, Owner access, granting the namespace
owner every login on every device. It is created when a namespace is born, and
also when a legacy namespace is upgraded with no policies of its own.

Without it, default deny would lock the owner out of their own namespace at the moment the mode
changed. Every other member starts with no access at all.

What authorization does not do Copy Chapter

It runs once, at the handshake. Revoking an identity or deleting a policy does not tear down a
session that is already open — that session was authorized when it started, and it continues
until it is closed.

The reason is not surfaced. A refusal carries a specific reason internally, but the connecting
client receives a generic access-denied. Connection Denied works
through the four possibilities.

Where to go next Copy Chapter

• SSH Identities — Binding keys to people.
• Access Policies — Writing the rules.
• SSH Access — Giving a pipeline its own way in.
• Login Approvals — When a login pauses for confirmation.

Ui Apps Docs Src Pages Manage Devices (`ui/apps/docs/src/pages/manage/devices.mdx`) Copy Section

layout: ../../layouts/DocsLayout.astro title: Managing Devices Copy Chapter

import Shot from '../../components/Shot.astro';

Managing Devices

Every machine running an agent appears under Devices.

<Shot id="device-list" route="/devices" of={{ role: "main" }} before={[{ click: { role: "button", name: "Sort by Hostname" } }]} alt="ShellHub Devices page listing accepted devices" />

How a device enrols Copy Chapter

Installing the agent is half of it. The other half is the device joining a namespace, and what
the agent was given at install decides both how it joins and whether anybody has to act on it.

Given nothing, the agent pairs: it asks the server for a code, prints it with a link, and waits
for somebody to accept it in the browser. That is the path the
Quickstart walks, and the one to use for a machine you are standing at.

A provisioning key is the answer at any volume. It names the namespace on its own and its mode
decides acceptance, so a fleet arrives accepted and tagged instead of arriving as a queue.

A tenant ID also names the namespace, and is how a legacy namespace enrolls every device: it
always leaves the device pending, in the queue behind the namespace's built-in key. A new namespace
still accepts it the same way, but it is deprecated, so nothing new should use it.

Statuses Copy Chapter

Only accepted devices can be connected to. A device sitting in pending is not broken — it is
waiting for somebody, on the activity of the key it enrolled with — see
Provisioning Keys.

Online and offline Copy Chapter

Separate from status. A device is online while its agent holds a connection to the server, and
offline when it does not.

The agent sends a keepalive every 30 seconds by default and reconnects on its own, waiting a
random 5 to 65 seconds before each attempt, so a brief network problem resolves itself without anybody doing anything. A device
that stays offline has a real cause — see
Device Not Appearing.

What identifies a device Copy Chapter

The agent's private key, at SHELLHUB_PRIVATE_KEY. Not the hostname, not the MAC, not the IP.

The consequences are worth internalizing:

• Rename the machine and it is the same device.
• Move it to another network and it is the same device.
• Lose the key — reflash, recreate the container, wipe the volume — and it is a new device,
  and the old entry stays behind.

Most confusing device lists are the result of that last one.

Names Copy Chapter

A device's name defaults to its hostname and is what you type in an SSHID:

$ ssh [email protected]@cloud.shellhub.io

You can rename a device in the console. Set SHELLHUB_PREFERRED_HOSTNAME on the agent when the
system hostname is not meaningful — a container with a random name, or a fleet where every unit
reports the same one.

Names matter beyond typing: the legacy public key ACL and firewall rules can select devices by a
hostname pattern, so a naming convention is something you can write rules against there. Access
policies select by tag instead — see Tags.

Details Copy Chapter

Opening a device shows its SSHID with a copy button, plus what the agent reports about it — OS,
architecture, agent version, when it was last seen.

$ ssh [email protected]@cloud.shellhub.io
#          ^^^^^^^^^ the namespace name

Sessions on this namespace are recorded.

$ ./bin/cli user list

$ ./bin/cli user create john_doe Secret123!- [email protected]

$ ./bin/cli user password john_doe NewSecret123!-

$ ./bin/cli namespace create engineering john_doe

$ ./bin/cli namespace member add myuser mynamespace observer

$ ./bin/docker-compose exec postgres pg_dump -U admin main | gzip > backup.gz

$ gunzip -c backup.gz | ./bin/docker-compose exec -T postgres psql -U admin main

# .env.override
SHELLHUB_DOMAIN=shellhub.example.com
SHELLHUB_AUTO_SSL=true
SHELLHUB_POSTGRES_PASSWORD=<not-admin>

$ make restart

# .env.override
SHELLHUB_TELEMETRY=false

$ make restart

level=info msg="telemetry is off: SHELLHUB_TELEMETRY is false"

$ ./bin/docker-compose ps
$ ./bin/docker-compose logs -f

$ make restart

# .env.override
SHELLHUB_LOG_LEVEL=debug
SHELLHUB_LOG_FORMAT=json

$ grep SHELLHUB_VERSION .env

$ ./bin/docker-compose pull
$ make stop
$ make start

$ ./bin/docker-compose ps
$ ./bin/docker-compose logs -f

$ head -3 agent/go.mod

$ git clone https://github.com/shellhub-io/shellhub.git
$ cd shellhub/agent
$ CGO_ENABLED=0 go build \
    -ldflags "-X main.AgentVersion=$(git describe --tags --abbrev=0)" \
    -o shellhub-agent .

$ export CGO_ENABLED=0 LDFLAGS="-X main.AgentVersion=$(git describe --tags --abbrev=0)"
$ GOOS=linux GOARCH=arm64 go build -ldflags "$LDFLAGS" -o shellhub-agent-arm64 .
$ GOOS=linux GOARCH=arm GOARM=7 go build -ldflags "$LDFLAGS" -o shellhub-agent-armv7 .
$ GOOS=linux GOARCH=arm GOARM=6 go build -ldflags "$LDFLAGS" -o shellhub-agent-armv6 .

$ SHELLHUB_SERVER_ADDRESS=https://shellhub.example.com \
  SHELLHUB_PROVISIONING_KEY=<your-provisioning-key> \
  SHELLHUB_PRIVATE_KEY=/etc/shellhub.key \
  sudo -E ./shellhub-agent

$ curl -s https://cloud.shellhub.io/info

$ git clone git://git.buildroot.net/buildroot
$ git clone https://github.com/shellhub-io/buildroot.git shellhub

$ cd buildroot
$ make BR2_EXTERNAL=../shellhub qemu_x86_64_defconfig

$ make BR2_EXTERNAL=../shellhub menuconfig

$ cat > rootfs_overlay/etc/default/shellhub-agent <<-EOF
SERVER_ADDRESS="https://cloud.shellhub.io"
PRIVATE_KEY="/etc/shellhub-agent.key"
PROVISIONING_KEY="<your-provisioning-key>"
EOF

$ git clone https://github.com/shellhub-io/ports.git /usr/local/shellhub-ports
$ cd /usr/local/shellhub-ports/shellhub
$ make install clean

shellhub_enable="YES"
shellhub_server_address="https://cloud.shellhub.io"
shellhub_tenant_id="<your-tenant-id>"

$ service shellhub start
$ service shellhub stop
$ service shellhub restart
$ service shellhub status

$ cd /usr/local/shellhub-ports && git pull
$ cd shellhub
$ make deinstall
$ make install clean
$ service shellhub restart

$ curl -sSf https://cloud.shellhub.io/install.sh | PROVISIONING_KEY=<your-provisioning-key> INSTALL_METHOD=standalone sh

$ sudo systemctl stop shellhub-agent
$ sudo rm -f /etc/shellhub.key

$ git clone https://github.com/shellhub-io/meta-shellhub.git
$ bitbake-layers add-layer ../meta-shellhub

IMAGE_INSTALL:append = " shellhub-agent"

SHELLHUB_SERVER_ADDRESS = "https://cloud.shellhub.io"
SHELLHUB_PROVISIONING_KEY = "<your-provisioning-key>"