How it works

The shape of it

Connection Shellius opens for you
Connection your own machine opens
API call

Shellius sits between your people and your fleet. It signs certificates, opens browser sessions itself, and answers every host that asks whether a certificate is still good.

The thick arrows are connections Shellius makes on your behalf; the dashed one is your own machine connecting directly. That distinction decides whether a private host needs a VPN — see Network reachability.

The parts

Part	What it does
Certificate authority	One Ed25519 key pair per organisation. The private key is encrypted at rest and decrypted in memory only while signing.
Policy engine	Decides whether a request is allowed, and whether it needs an approver. Deny rules beat allow rules.
`check-principals`	A small script on each host. `sshd` runs it on every connection and it asks the API whether this certificate is still good.
Heartbeat timer	A systemd timer that reports the host as reachable.

Bootstrapping a host

Bootstrapping ships the CA public key and a validation hook to the host. The CA private key never leaves Shellius.

An operator with the servers.onboard permission asks Shellius for a bootstrap command. Shellius mints a one-time, 30-minute token and returns a command to run on the target:

bash

curl -fsSL "https://shellius.example.com/api/bootstrap/install.sh?token=…" | sudo bash

The script writes the organisation's CA public key to the host, points sshd at it with TrustedUserCAKeys, installs check-principals with a narrow sudoers drop-in, sets up the heartbeat timer and a logrotate rule, and validates the sshd configuration before reloading. The host also receives its own agent token, which is what it uses to authenticate back to the API.

The CA private key never leaves Shellius.

INFO

The bootstrap token is one-time and expires after 30 minutes. If it is consumed or expires, generate a new one — the same server can be bootstrapped again, and --upgrade re-installs the agent components without touching CA trust or sshd.

Requesting access

Home / Access requestsSearch… Ctrl K

Requesting access to a production server. Interface preview with sample data.

A request names a server and a duration. The policy engine evaluates it:

Deny rules first. If any deny rule matches, the request is refused.
Allow rules. An allow rule has to match for the request to proceed, and it determines which principals and what maximum lifetime are available.
Production check. If the server's environment is prod, the request goes to an approver — unless the requester's role holds access.prod_bypass and the organisation has prodBypassEnabled turned on. Even then the request is still created, still requires a reason, is audited as access_request.prod_bypass, and the server's approvers are notified.

A policy's autoApprove flag cannot grant unreviewed production access. That is deliberate: auto-approval is for development and staging.

Connecting

Once a request is approved, Shellius signs a certificate containing:

the principals the policy granted (the Unix accounts you may log in as),
a validity window bounded by the policy's maximum lifetime,
a key ID identifying the user, the server, and the request,
optional critical options such as a source address restriction.

The private key is generated per request, returned once, and never written to Shellius storage.

You can then connect from the browser terminal, or from the shellius terminal client, or by using the certificate with your own ssh client.

Those are not the same network path, and the difference matters:

Route	Who opens the TCP connection	Needs to reach the host
Browser terminal	The Shellius backend, over `ssh2`	The backend
RDP in the browser	`guacd`, alongside the backend	The backend
`shellius` terminal client	Your machine, by running `ssh`	Your machine
Downloaded key + your own `ssh`	Your machine	Your machine

So a host on 10.x is reachable in the browser from anywhere, provided Shellius itself sits on that network — no VPN required for the user. The same host is unreachable from the terminal client unless your laptop is on the network too. The portal flags private addresses for exactly this reason.

Network reachability covers the consequences, including what it means for the trust you place in the backend.

A request, end to end

Why revocation is fast

sshd runs check-principals on every connection. Revoking in Shellius changes the answer, so the same unexpired certificate stops working without touching the host.

This is the part that makes certificates safe to hand out. On every incoming connection, sshd runs check-principals, which calls the Shellius API with the host's agent token and asks whether this certificate is still valid and the access still granted.

So revoking access does not require touching any host, and does not wait for the certificate to expire. The next connection attempt is refused. Sessions already open are ended separately by terminating the session.

What gets recorded

Every request, approval, denial, certificate issued, session opened, and revocation is written to the audit log with the actor, the target, the time, and the source address. The log is append-only — there is no update or delete path. SSH sessions can additionally be recorded as asciinema casts and replayed in the portal.

Next steps

Shellius vs. static keysWhat this replaces.QuickstartTry the whole flow on one host.Threat modelWhat Shellius protects, and what it trusts.

The shape of it ​

The parts ​

Bootstrapping a host ​

Requesting access ​

Connecting ​

A request, end to end ​

Why revocation is fast ​

What gets recorded ​

Next steps ​