Security model
Understand how Subshell protects access to sessions and machines, and which risks your deployment must address.
Deployment assumptions
Subshell is self-hosted software for a developer's machine or a trusted network, such as a LAN, VPN, or private mesh. It runs real programs on machines you enroll. It isn't designed for direct, unrestricted exposure to the public internet or for hosting mutually untrusted tenants.
The server is a trusted control plane. It stores account and session information, serves the dashboard, and authorizes work on enrolled nodes. A compromise of the server's OS account can compromise the entire fleet. Administrators manage the instance and its security settings. They need the same sharing grants as other users to view or control someone else's sessions.
Use the following boundaries when evaluating a deployment:
| Boundary | Protection | Important limit |
|---|---|---|
| Unauthenticated caller → server | Authentication on protected API routes and WebSocket attachment | First-run setup is reachable before an administrator exists. |
| Signed-in user → another user's session | Ownership and explicit view or edit grants | Administrators need the same sharing grants as other users. |
| Agent → Subshell API | Scoped pane credentials, resource checks, and refusal on instance-administration routes | A pane can act on other sessions owned by its user. |
| Server → enrolled node | Encrypted application-layer connection and signed, target-bound commands | The server is authorized to run programs as the node's execution account. |
| Agent → agent channel | End-to-end encryption of message bodies and peer-key pinning | Metadata, terminal output, and compromised endpoint keys are outside this protection. |
| Agent → machine filesystem | The execution account's OS permissions | Subshell doesn't sandbox agents. |
The server sits between viewers and execution machines:
Browsers connect to the server, not directly to each node. Both the server and the execution account remain trusted endpoints.
Authentication and account controls
Subshell supports password sign-in, passkeys, and configured OpenID Connect (OIDC) providers. Provider settings control registration and, where configured, approval of new accounts. The first account becomes the administrator; protect the setup address until you complete that step. See Registration policy and Sign-in providers.
Passwords are stored as hashes rather than plaintext. Protect the database nevertheless: it also contains active authentication and enrollment data.
Browser authentication uses an HttpOnly session cookie with SameSite=Lax. HttpOnly prevents browser scripts from directly reading the cookie. The Secure flag depends on the configured public base URL being HTTPS; a plain HTTP deployment doesn't receive that protection merely because it runs in production mode.
Password sign-in has per-email exponential backoff, capped at 30 seconds. This limits repeated guesses against an account. It isn't general API rate limiting or denial-of-service protection.
Passkeys authenticate through WebAuthn and create the same browser session as password sign-in. They are an alternative sign-in method, not an enforced second factor. Their relying-party hostname comes from the configured public base URL. Using another hostname for the same server can prevent a passkey from working. See Sign-in and origin errors.
Disable an account or recover access
Disabling an account revokes its browser sessions, rejects its pane credentials, closes its terminal and dashboard connections, invalidates outstanding WebSocket attachment tokens, and disconnects its enrolled nodes. Re-enabling the account lets its nodes reconnect with their existing node credentials.
A password reset has a narrower effect. It revokes stored browser sessions but doesn't remove passkeys or close already-connected WebSockets. Use account disabling when you need to cut off an account's active access during an incident. Administrators manage this from Settings → Server Settings → Users in the server dashboard's sidebar; see Users and roles.
Emergency administrator recovery overwrites the administrator's stored password. It is audited and shown as a warning to signed-in users. Clear the emergency value from every configuration layer and restart after recovery. Follow Account recovery, which links to the relevant configuration paths.
Authorization and session sharing
A session is private to its owner by default, including from administrators. Unauthorized session reads return 404, and private sessions are omitted from lists, so another user can't confirm their existence by probing an ID.
Owners can share sessions with named users or Everyone, meaning all signed-in users on the instance:
- View allows live terminal viewing and access to captured output.
- Edit adds terminal input and operations such as rename, restart, and termination.
- Deletion, managing shares, and the owner's notification bell remain owner-only, including for administrators.
A view grant can expose credentials printed in terminal output. An edit grant lets the recipient send input to a real shell or agent, except in an SSH subshell. SSH input requires its owner’s browser session; edit grantees and bearer credentials cannot type into it. Sharing also exposes attached viewer information, such as device labels and whether a viewer can type. These permissions don't create an isolated copy of the process.
Changing a subshell's shares closes its non-owner terminal connections, including connections still attaching. Reconnecting checks the current effective grant: users who no longer have access can't view the terminal, and users with only View access can't send input. This doesn't stop the running shell or undo commands already accepted.
Sharing a node is a separate decision: even a view grant on a node permits the recipient to launch their own sessions there. The execution account and machine can access those processes and their files. Sharing a node doesn't automatically share every session on it. See Access model, Share a subshell, and Share a node.
Preview security
Permissions and access links
Web previews and virtual displays have separate opt-in settings on each node. The node's owner or a Manage grantee also controls which display providers are allowed. A successful requirements check doesn't enable a feature or grant permission. App forwarding and virtual-screen input need edit access to the subshell. View access permits browser-frame watching, restricted to the browser discovered for that shared subshell.
Website isolation
By default, forwarded websites run in an opaque-origin browser sandbox, including when opened in a separate browser tab. Their scripts can't read the dashboard DOM, storage, or authenticated API responses. Target cookies stay in a per-preview server-side jar rather than being installed on the dashboard origin. Browser storage, service workers, and some website login flows need the node's normal browser context; use Virtual display for those checks.
The explicit Run outside the sandbox option removes that isolation for an app you fully trust. Its scripts can access the dashboard, browser storage, and your Subshell session, and act with your account's permissions. These previews require the opening account's current cookie on HTTP requests. Credential filtering and the target cookie jar still apply; the option doesn't guarantee app compatibility. Read the configuration warning before enabling it.
The preview proxy can rewrite app HTML, styles, and module imports, and inject a compatibility script to keep common app requests under the private preview URL. This changes the responses your browser receives. Integrity hashes on rewritten local script and stylesheet references no longer apply and are removed; unrelated external resources keep their integrity checks. The server remains a trusted intermediary. A target's Content Security Policy stays effective apart from its framing restrictions and can still block the compatibility script.
Personal preview settings control URL rewriting, redirects, and which Host header the app receives. They're saved for you by node, host, protocol, and port, and apply when a fresh preview opens. Those three options don't relax the sandbox, grant access to another target, disable HTTPS certificate checks, or make every app compatible. Text rewriting and decompression have size and concurrency limits; these aren't general protection against denial-of-service attacks.
Link lifetime and revocation
The preview URL is a bearer access link. Anyone who obtains it can use it while it remains valid. Keep it out of public issues, shared browser history, and reverse-proxy access logs. Closing the tab releases its connections but doesn't immediately revoke a copied link. Forward sessions expire after 15 minutes without traffic; losing the required sharing permission, account disable, subshell death, and node loss also cut off affected access. Losing edit access closes app forwarding and virtual-display access. Turning off Allow web previews or Allow virtual displays blocks new operations for that feature without immediately closing existing connections. To revoke access, remove the grants that provide it or end the subshell.
Transport and network reach
The server sees forwarded website bytes and browser frames. The node link is encrypted, but this is not end-to-end encryption from your browser to the app. Automatically discovered apps use loopback. Saved services can reach an explicit host from the node, with edit access and node opt-in required. HTTPS connections validate the destination certificate on the node. Saving a service does not expose a new public listener. Edit access retains the execution account's authority over its local services; port discovery isn't an OS isolation boundary.
macOS helper consent and desktop control
macOS virtual displays share the signed-in account's desktop, pointer, and keyboard focus. The helper can capture a Subshell virtual screen and control apps on it after explicit local consent and macOS permission grants. It refuses main, built-in, and mirrored screens, but this isn't isolation from the rest of the account. Notifications or other windows on that virtual screen may be visible. Its native Disable helper control stops all capture and input; the dashboard and MCP cannot turn it back on. See helper setup and disable instructions.
VNC and local users
Both Linux and macOS virtual displays use a local VNC-compatible listener. The preview connection provides remote authorization; the local listener has no separate password. Other local users who can reach it can control the screen. Linux also uses a private Xauthority file to protect the X server, which doesn't add authentication to VNC. Don't enable virtual displays on a host shared with untrusted local OS users. GUI apps and agents retain their normal execution-account permissions. Don't expose the VNC port through a network port forward. A copied preview link also grants control until it expires or is revoked; view-only sharing doesn't offer a read-only VNC viewer.
Follow Web previews & screens for setup and the preview architecture for the data path.
Machine credentials
Credentials serve different purposes:
| Credential | What it permits | Lifecycle |
|---|---|---|
| Browser session | User access, including administration when the user is an administrator | Revoked by sign-out, account disable, or password reset. |
| Pane token | Permitted API operations as the session's owner, without administrator privileges or inherited session-sharing grants for detail and write operations | Revoked on termination or deletion and rotated on restart. |
| System API key | Integration access as the system service identity, without a pane permission map | Long-lived until disabled or deleted. |
| Node credential | Authenticate that node's daemon connection | Replaced by key rotation or invalidated by node deletion. |
| Setup key | Enroll one node | Single-use, expires after 24 hours, and can be revoked before use. |
Administrative endpoints require an administrator's browser session; bearer credentials are refused. System keys don't inherit the administrator's human resource ownership. Treat them as powerful integration credentials and revoke unused keys.
A pane token isn't confined to its single session. It can act on its owner's other sessions and prompt library. The session list can also reveal shared sessions visible to that owner, even when the pane token can't inspect or change them. A compromised or prompt-injected agent therefore has a wider API boundary than its own terminal. See API keys and Communication security.
Network and WebSocket protection
The server listens on all interfaces by default. Network reachability and permission to sign in are separate controls. Firewall rules and your private network determine who can reach the port; Subshell authentication and resource permissions determine what an admitted caller can do.
Browser origins are checked against a registry derived from the server's configured addresses, its LAN interface addresses on a wildcard bind, administrator-supplied extra origins, and enabled network plugins. The registry doesn't trust an arbitrary requesting hostname. Configuration controls reject new wildcard origin entries. This limits cross-origin requests and DNS-rebinding attacks, but an origin allowlist isn't a firewall or protection against a non-browser client.
Use HTTPS for browser access across a network. The browser-to-server HTTP and WebSocket connections don't inherit the node link's application-layer encryption. A VPN may protect transport, but browser features such as passkeys and web push still need a secure context.
WebSocket attachment tokens expire after 30 seconds and can be redeemed once. Bearer-minted tokens are bound to one session; a pane token can mint one only for its own session. The dashboard feed refuses these session-bound tokens. Same-host attachment can also authenticate with the browser session cookie, so not every WebSocket connection uses an attachment token.
Already-connected WebSockets aren't continuously re-authenticated. Account disabling explicitly disconnects them, and subshell sharing changes close non-owner terminal connections so their grants are checked again. Password resets don't close already-connected WebSockets. Don't assume changing a credential disconnects every live connection.
Terminal WebSocket input has per-message, per-connection, and instance-wide limits. Oversized or excessive input closes the affected connection. Pending input is discarded when the viewer disconnects; already-dispatched work remains counted until it settles. These bounds limit retained input work, not the commands an authorized user can run or the resources those commands can consume.
For a public Cloudflare Tunnel, Subshell requires a Cloudflare Access gate and verifies signed Access assertions with the configured issuer and audience. The gate doesn't replace Subshell sign-in. Follow Cloudflare Tunnel; publishing a hostname without the verified gate doesn't satisfy the trusted-network deployment model.
Use LAN access, HTTPS and reverse proxies, and Server addresses to configure this boundary.
Node encryption and command verification
Enrolling a node delegates command execution under that machine's OS account to the trusted server. Use an execution account whose filesystem access and credentials match the work you intend to run there.
The node connection uses application-layer encryption. The endpoints pin long-term public keys and derive per-connection keys with libsodium crypto_kx; established connections carry secretstream ciphertext. A broken encrypted stream fails the connection rather than continuing with plaintext. This protects node traffic even when its WebSocket transport isn't TLS.
Commands also carry ES256 signed envelopes. Each envelope names one target node, expires after 30 seconds, and has a single-use identifier checked against replay. A node verifies the signature, target, and freshness before executing a command. Encryption protects confidentiality; signing limits who can authorize work and where a command can run.
Enrollment and first pairing remain trust decisions. The setup credential and the address you give the node determine which server it pairs with. Encryption after pairing doesn't independently prove that the first server was the one you intended. Use a trusted enrollment path and address. Older nodes held for a protocol upgrade have a plaintext update-only recovery path; this isn't permission to run ordinary work over a downgraded link.
Neither encryption nor signing protects a node from a compromised server that holds the signing keys. Repointing a node also sends its node credential to the newly named server, so treat an address change as a credential-handling decision. See Node protocol and Repoint a node.
Execution restrictions aren't a sandbox
Node directory allowlists restrict starting directories, including resolved-path checks on launch and restart. An empty allowlist means unrestricted starting directories. Running agents can still access any file allowed by their execution account.
The server filesystem picker is available to signed-in humans and refuses machine credentials. Its optional filesystem root narrows browsing, not agent execution or remote-node access. See Directory restrictions and Files and paths.
The node's local management dashboard listens on loopback and has no login. Host, Origin, and JSON-content checks protect against browser rebinding and cross-site mutations. They don't prevent another local OS user from reaching the port. On a machine with untrusted local users, disable that dashboard using the configuration guidance in Node CLI and Files and paths.
Agent communication encryption
MCP channel bodies are encrypted per recipient using P-256 ECDH-ES and A256GCM in General JWE envelopes. Encryption and decryption happen in the MCP processes; the server stores and forwards ciphertext. A read of the channel database alone doesn't reveal message bodies.
Senders pin each peer's public key on first use. A subsequent key change blocks posting until the operator verifies it and repairs the pin. This detects later key substitution; it doesn't independently authenticate the first key.
The protection excludes channel names, membership, authors, timing, ordering, and message sizes. It also excludes terminal streams and captured transcripts. The execution account can read accessible identity keys, and a compromised endpoint can read its decrypted messages. See Communication security for the exact boundary and key-recovery procedure.
These two paths have different encryption boundaries:
HTTPS in the first path is your deployment's transport protection. Channel encryption in the second path protects message bodies from server storage; it doesn't make the entire product end-to-end encrypted.
Stored data and secret exposure
Subshell doesn't encrypt all stored data. OS permissions, host security, disk encryption, and backup protection remain important.
| Data | Storage and exposure |
|---|---|
| Session transcripts | Plaintext terminal output on the execution machine. Logs use 0600 permissions in a 0700 directory. Echoed input and printed secrets can be retained. |
| Channel bodies | Ciphertext on the server; recipient identity keys live on execution hosts. |
| Account and configuration database | Sensitive account, session, and configuration records. Protect the database and its backups as credentials. |
| Outstanding setup keys | Plaintext in the database so authorized users can retrieve them; single-use and time-limited. |
| Signing keys, node configuration, and agent identity keys | Sensitive files protected by filesystem permissions, not from the OS account that owns them. |
| Uploaded files | Remain in the session's working directory until removed. They aren't automatically swept. |
Stopped server-host session logs age out after 30 days by default; remote nodes default to one day. Running-session logs aren't swept. Deleting a session removes its log, but offline-node cleanup and independently retained backups must also be considered. Configure retention on the machine that stores the log; Files and paths identifies the configuration layers.
Pane bearer tokens and typed input can also appear in process arguments or tmux metadata. A local process with sufficient access can read them. Curated launch environments avoid forwarding server application secrets automatically, but they don't prevent agents from reading files available to their OS account.
Generated node-enrollment installers keep setup keys out of child-process
arguments, including during Set up Subshell here over SSH. This doesn't
protect them from root or the same OS account. Copied commands can remain in
shell history, and manually passing --key still exposes that argument to
process inspection. Treat setup commands as credentials; see
Make the destination a node.
Browser push notifications pass through the browser's push service and can display a session name on a lock screen. Notifications are owner-targeted; sharing a session doesn't notify every grantee. Agent-provider traffic is separate from Subshell: an agent may send project content to its configured provider. Self-hosting Subshell doesn't make that provider interaction local.
Backup and restore protection
Full archives contain live credentials, including the authentication secret, identity keys, and plugin secrets. Encryption defaults off. Treat an unencrypted archive as sensitive server data and keep backup copies outside the server machine in protected storage.
Optional encryption uses AES-256-GCM with a fresh random salt and nonce for each archive. The header and ciphertext are authenticated before decrypted archive contents are parsed. Password derivation uses scrypt with fixed settings: N=65536, r=8, and p=2. Working memory is about 64 MiB, with a 128 MiB scrypt allowance. This is a derivation allowance, not a cap on the server or desktop app's total memory.
Every machine uses the same work factor. A fast backup host doesn't increase the cost for a slower restore host. There is no hardware calibration or artificial waiting period. Actual processing time depends on hardware and load; there is no guaranteed three-second maximum.
Archive passwords require at least eight Unicode characters and permit long passphrases. Eight characters is a usability minimum, not a guarantee of strength. An attacker with an archive can make unlimited offline guesses using their own hardware. Increasing derivation work slows guesses, but doesn't provide rate limiting or make a short password equivalent to a strong longer one. Prefer a unique randomly generated password or passphrase, and store it separately. Forgotten passwords can't be recovered.
See Backups and restoration for procedures, archive scope, and recovery verification.
Plugins, installers, and updates
Plugins run in the server process with its privileges and aren't sandboxed. Installing a third-party plugin is an administrator trust decision affecting the instance and its enrolled nodes. A plugin manifest or capability check doesn't establish that its implementation is safe. See Plugins.
Administrator-requested agent installers run vendor installation commands under the server's OS account. Subshell also launches agent binaries found on execution hosts without independently verifying those binaries. Evaluate the agent and plugin supply chains as well as Subshell itself.
Subshell's update paths verify a publisher-signed release manifest and the downloaded artifact's SHA-256 digest. Nodes verify updates independently rather than accepting the server's assurance alone. This protects against an update host replacing an artifact with unsigned code; it doesn't protect against compromise of the publisher's signing key or replay of an older signed release.
The desktop apps also verify Display Helper's bundle identity and, in release builds, its publisher signature before using an installed helper, not only when installing a new copy. Signature verification doesn't replace the local consent and macOS permissions described above.
First-install shell scripts have a different trust boundary: their integrity checks use digests served by the same release source, so initial installation still relies on HTTPS and repository trust. Don't assume update verification makes every installation method identical. See Update the server.
Audit and incident response
Subshell records security-relevant actions such as sign-in and sign-out, user and role changes, password resets, key creation and revocation, node enrollment, sharing, network configuration, and update operations. Audit entries identify actors and affected resources without recording password or key values.
The audit trail isn't a complete terminal-command history. Failed login attempts aren't audit events, and terminal input isn't recorded as individual audit actions. Captured terminal transcripts are a separate, sensitive artifact. Audit records live on the same trusted server; they aren't an independently protected, tamper-proof log.
The server's operational log is separate again: it is size-bounded and replaced when full. Debug request logging can expose paths and setup-key-bearing request lines. Leave debug logging off unless you need it, and review logs before sharing them. See Audit log and Status and logs.
During suspected account compromise, disable the account, review passkeys and credentials, and inspect the audit trail. During suspected host or server compromise, treat readable identity keys, session transcripts, provider credentials, and node-signing keys as exposed. Rotating a user's password alone doesn't repair a compromised execution host or control plane.
Evaluate your deployment
Before admitting users or enrolling machines, establish:
- Who can reach first-run setup and the running server, and which network or identity gate enforces that perimeter.
- Which administrators, plugins, and server OS accounts you trust with fleet-wide command execution.
- Which users may launch on each node, and what that execution account can read.
- How browser transport, enrollment, disk storage, and backups are protected.
- How session sharing, transcripts, channel metadata, and notifications affect sensitive work.
- How you revoke access, rotate credentials, and investigate incidents.
General denial-of-service protection, complete API rate limiting, enforced multifactor authentication, agent sandboxing, and separation of administrator duties aren't provided by this model. Deployments requiring these controls need additional infrastructure or a different isolation design.
For implementation evidence and the full accepted-risk accounting, read the detailed security model. Use Access model and Communication security for the focused permission and encryption references.
Edit on GitHubLast updated on
