Shellbeam

Your development machine, within reach.

Shellbeam is an independent, self-hosted remote development workspace. This release provides a real terminal, scoped file editing, structured Git operations, coding-agent attention tracking, host-controlled device approval and revocation, and automatic outbound Cloudflare Quick Tunnel access from a React browser interface.

[!IMPORTANT] Shellbeam is an early clean-room release, not a production remote-access appliance. Device and approval state is currently in memory. Remote desktop, native desktop/mobile shells, persistent host state, TURN, and local-site proxying remain deliberately unavailable.

What works

• One-scan pairing with a single-use secret, revocable credentials, and an optional explicit-approval mode.
• Real Socket.IO terminal transport with bounded, versioned Shellbeam messages and replay sequencing.
• Filesystem access confined to one operator-approved canonical workspace root.
• Structured Git status, diff, branch, commit, and push operations without shell-built commands.
• Static Vite 8 + React 19 interface with terminal, files, Git, pairing, and local-only Host control.
• Responsive terminal sessions with Focus and Split layouts, up to four simultaneously visible terminals, per-session connection status, reconnect-safe output replay, mobile quick keys, and a compact landscape rail that never covers terminal output.
• Clipboard paste, drag-and-drop, and file-picker attachments for live coding-agent drafts. Files are copied into a private OS temporary directory and inserted through terminal paste semantics without pressing Enter.
• Mobile workspace navigation with persistent terminal/editor state, a responsive CodeMirror editor with lazy syntax modes and Ctrl/⌘ S, folder traversal, file creation/editing/rename/copy/delete, and Git actions.
• A responsive agent inbox that normalizes official Codex, Claude Code, and OpenCode lifecycle hooks into working, waiting, approval-needed, finished, and failed states. Meaningful unseen updates become unread; routine working heartbeats remain quiet in History, while unresolved blockers stay in Inbox even after being read.
• Opt-in browser notifications when an agent needs attention, with a direct jump back to its live terminal. Shellbeam does not parse terminal output to guess agent state.
• Loopback-only host binding plus a managed, checksum-verified official cloudflared Quick Tunnel.
• The same pairing code and compact QR in the terminal and local Host Control UI, with visible tunnel and terminal readiness.
• A metadata-only Cloudflare Worker/Durable Object rendezvous implementation. It is not a terminal, SDP, ICE, screen, file-content, or TURN relay.

Security posture

• Pairing and device credentials are random 32-byte secrets; only digests enter host state.
• The default one-use QR grants a fixed set of terminal and workspace capabilities; --require-approval keeps grants behind an explicit local decision.
• Device inspection, approval when enabled, and revocation stay on the machine being controlled.
• Outside streamer mode, the local admin secret is printed once inside the loopback Host Control fragment and sent only in its same-origin authority header.
• Origins, credentials, capabilities, payload shapes, and byte limits are rechecked at the authority boundary.
• Direct dependencies are exactly pinned and restricted by the repository dependency policy. CI audits the frozen lockfile and verifies the accepted installed-license set.
• Terminal output, commands, screen frames, and keystrokes are not persisted by Shellbeam. Draft attachments are retained only in a private per-run OS temporary directory and deleted when the host stops.

Read the threat model before exposing a host. Quick Tunnel is intended for development and onboarding; use an authenticated, explicitly configured managed tunnel before relying on Shellbeam in a stable environment.

Install, run, scan

The release CLI supports macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows (x64 and ARM64). Install Bun 1.4.x, then:

bun install --global shellbeam
cd /path/to/your/project
shellbeam

To test the same release package locally:

bun install --frozen-lockfile
bun run build:package
npm pack
bun install --global ./shellbeam-0.1.12.tgz
shellbeam

Shellbeam immediately serves local Host Control, prints the one-use pairing code and QR, downloads the pinned official cloudflared asset when absent, verifies both archive and executable SHA-256 checksums, and creates a temporary tunnel. Scan the remote QR; its one-use secret is included in the URL fragment and the browser receives revocable default terminal/workspace access without a second approval step. The fragment is removed before the browser continues and is not sent as a referrer.

On first launch Shellbeam also merges its managed hooks into existing Codex and Claude Code hook files and installs a dependency-free OpenCode plugin. Existing hooks are preserved. Agents started inside a Shellbeam terminal inherit a loopback-only, per-run hook capability, so their activity can appear in the Agents workspace without exposing that ingress through the public tunnel. Use --no-agent-hooks when you do not want Shellbeam to manage these files. This release reports attention and opens the corresponding terminal; approvals and answers still happen in the agent's own terminal. Read state is kept locally per paired device so a refresh does not recreate already-reviewed work.

Inside a connected terminal, paste an image/file from the clipboard, drop it on the terminal, or choose Attach. Shellbeam accepts up to four files per action and 10 MiB per file, stores opaque random copies with owner-only permissions in the operating system temporary directory, and pastes their paths into the live agent composer. Codex and Claude Code render supported images as attachment chips. The draft is deliberately not submitted; inspect it and press Enter yourself. Attachments are removed when Shellbeam stops. Browser paste shortcuts stay in the browser, so a remote Codex or Claude process never tries to read the host machine's unavailable X11/macOS/Windows clipboard; ordinary text paste continues through xterm normally.

The complete QR/link is a temporary bearer capability. Use --require-approval if every new device must also be confirmed in local Host Control. For screen sharing or streaming, configure a private admin secret and hide all secrets and QR output:

SHELLBEAM_ADMIN_SECRET="$(bun -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')" shellbeam --streamer-mode

Streamer mode still starts and reports the tunnel, but prints neither the admin secret nor a pairing secret. Open local Host Control, enter the configured admin secret privately, and use Create private pairing QR when you are ready. Prefer the environment variable over --admin-secret, because command-line arguments may be visible to other local processes.

The local UI reports installing, starting, verifying, connected, or unavailable. Shellbeam tries Cloudflare's automatic transport and then an explicit HTTP/2 fallback, retries three times with bounded backoff, and exposes an immediate Retry tunnel action in local Host Control. If both UDP and TCP access to Cloudflare port 7844 are blocked, it says so without falsely showing a connection; loopback remains usable. Use --local-only to skip all tunnel setup, or --cloudflared /absolute/path to use a reviewed local binary instead of the managed one.

Bun supplies the real PTY through openpty() on macOS/Linux and ConPTY on Windows, so a release install needs no C/C++ compiler. Cloudflare does not publish a Windows ARM64 binary for the pinned release; Shellbeam therefore works locally on Windows ARM64 while its automatic tunnel reports unavailable instead of downloading an unverified substitute.

Develop from source

Prerequisites: Bun 1.4.0 and Node.js 20.19 or newer for the compatibility suites.

Install, validate, and build:

bun install --frozen-lockfile
bun run check

Start the built web interface and host against one approved workspace:

bun run --filter '@shellbeam/web' build
bun run --filter '@shellbeam/host' build
bun run --filter '@shellbeam/host' start -- \
  --workspace /absolute/path/to/project \
  --shell /bin/bash \
  --static-dir apps/web/out

The host still binds only to 127.0.0.1. Shellbeam starts cloudflared without a shell, accepts only the exact canonical HTTPS URL it reports, verifies public reachability before showing connected, and keeps device authority and revocation on local Host Control.

Architecture and provenance

React browser / installable web shell
              |
       HTTPS + Socket.IO
              |
Shellbeam host on 127.0.0.1
       |            |              |
 Bun native PTY   files + Git   agent hooks
              |
LAN access or outbound Quick Tunnel

The canonical behavior is in requirements, the implemented and deferred surfaces are in architecture, and the independent-development boundary plus complete public-doc inventory are in the clean-room record. Package decisions are documented in dependencies and enforced by the dependency policy.

The testing contract defines the enforced 100% instrumented-code coverage boundary and the built-process smoke evidence for stateful adapters and presentation code. The tunneling review records the external architecture comparison and accepted safety decisions.

Shellbeam is not affiliated with, endorsed by, or derived from 9Remote or its authors. No upstream source code or protected assets were used.

Network-source configuration

Shellbeam is licensed under the GNU Affero General Public License v3.0 only. If you modify and deploy it for network users, configure the web build with a source URL that gives those users the complete Corresponding Source for the exact deployed version:

VITE_SHELLBEAM_SOURCE_URL=https://example.org/source/shellbeam bun run --filter '@shellbeam/web' build

The development default points to this repository. A private repository URL does not satisfy that deployment obligation for users who cannot access it.

Contributing

See CONTRIBUTING.md for the test and dependency gates and SECURITY.md for private vulnerability reporting guidance.

Copyright © 2026 Shellbeam contributors.