content.json

{
  "version": "0.8.1",
  "pages": {
    "docs": {
      "eyebrow": "Documentation",
      "title": "Share any terminal process with one link.",
      "intro": "shell.online wraps a command in a local PTY, keeps it running on your machine, and exposes its live terminal through an interactive or server-enforced read-only URL.",
      "cards": [
        ["Install", "Run curl -fsSL https://shell.online/install | sh on macOS, Linux, BSD, or Solaris; on Windows PowerShell use irm https://shell.online/install.ps1 | iex. Both installers verify SHA-256 before writing the binary and print PATH instructions when needed."],
        ["Start a share", "Prefix an existing command: shell claude, shell codex, or shell python train.py. Omit the command for a fresh shell. The URL prints after the relay exists and the task survives a short usability handshake; a task that exits immediately produces no dead link."],
        ["Choose access", "Links are interactive by default. Add --read-only before the command when viewers should monitor without being able to send terminal input."],
        ["Encryption is automatic", "Every normal share is E2EE. shell prints an eight-character browser password with the URL; set SHELL_ONLINE_E2EE_PASSWORD to use a longer one. --no-e2ee is an explicit compatibility opt-out. Use Docker when the same encrypted shell and URL should survive container restarts."],
        ["Manage locally", "Use shell list to see local process uptime and the relay's independent online, reconnecting, expired, or unknown state. Use shell attach <ID> to take over locally and shell kill <ID> to stop one. Task exit always closes an ordinary share."]
      ]
    },
    "mobile": {
      "eyebrow": "Terminal fidelity",
      "title": "A real terminal, fitted to the device in your hand.",
      "intro": "A phone is not a smaller desktop. shell.online uses a spacious 120×36 session grid until a phone connects, then atomically switches everyone to a compatible 80×24 grid and fits it to each browser.",
      "cards": [
        ["Deterministic sizing", "Viewers never own PTY sizing. Desktop-only sessions use 120×36. Any connected phone selects the session-wide 80×24 compatibility grid before input is forwarded; the last phone leaving restores 120×36. Read-only phones count too."],
        ["Touch that scrolls", "Single-finger gestures scroll normal terminal history. When an application enables mouse tracking or its alternate screen, the same gesture is translated into terminal wheel input."],
        ["Keyboard-aware", "The terminal follows visualViewport changes through keyboard open, dismiss, rotation, and browser chrome movement. Ctrl-C, Ctrl-W, selection-copy, and binary terminal replies have dedicated paths. Browser Ctrl-D warns on its first press and sends EOF only when deliberately repeated within three seconds."],
        ["Large paste, bounded", "Paste input is split into Worker-safe 16 KiB frames and waits for WebSocket backpressure. A browser cannot turn one large paste into an unbounded memory queue."]
      ]
    },
    "reliability": {
      "eyebrow": "Process continuity",
      "title": "The link can disappear. Your process should not.",
      "intro": "The PTY and command live on your machine. Relay and browser failures are treated as recoverable display failures, never as permission to terminate local work.",
      "cards": [
        ["Automatic reconnect", "The CLI and browser reconnect with bounded backoff. A temporary network failure does not stop the process, and the same ordinary share link remains recoverable for 12 hours after its host disconnects."],
        ["Screen recovery", "A bounded local ring buffer restores new or returning viewers. If live output outruns either network or rendering, shell.online drops stale display work and sends one authoritative screen snapshot."],
        ["Backpressure by design", "PTY reads never wait indefinitely for Cloudflare. WebSocket writes time out, queues are bounded, frames have size and traffic limits, and high-output processes keep running locally."],
        ["Explicit lifecycle", "The URL prints only after a short startup usability handshake. If the task has already exited, shell reports its status without printing a dead link or attach/kill instructions. shell list distinguishes local process liveness from relay status; shell attach rejoins locally and shell kill stops the process. Ordinary shares and server state disappear when the task exits."]
      ]
    },
    "security": {
      "eyebrow": "Trust model",
      "title": "Know exactly what the link grants—and what the relay sees.",
      "intro": "The current CLI encrypts terminal payloads on the machine and decrypts them in the browser by default. Cloudflare routes authenticated ciphertext while explicit metadata and bearer-access limits remain; --no-e2ee deliberately changes that boundary.",
      "cards": [
        ["URL plus password is a bearer capability", "Anyone holding both values for an interactive share can view and type with the wrapped process’s operating-system permissions. Share them only with intended collaborators and run with least privilege."],
        ["Read-only is server-enforced", "With --read-only, ordinary browser input and confirmed EOF are rejected by the Worker. DevTools or handcrafted WebSocket frames cannot turn the link into an interactive session."],
        ["Cloudflare relays ciphertext by default", "The current CLI normally encrypts terminal payloads before the relay. Cloudflare can still observe frame type, encrypted size, timing, connection IP, access mode, command label, and lifecycle metadata. --no-e2ee instead exposes terminal payloads to Cloudflare while retaining HTTPS/WSS transport encryption."],
        ["No terminal transcript retained", "Cloudflare does not persist terminal contents. The CLI holds only a bounded in-memory replay buffer while the process is alive; ordinary task exit deletes the session state and closes every socket."]
      ]
    },
    "e2ee": {
      "eyebrow": "End-to-end encryption",
      "title": "Terminal contents only the machine and its browsers can read.",
      "intro": "E2EE is automatic by default. New shares encrypt terminal payloads with AES-256-GCM before they enter the relay; password derivation happens on-device and URL fragments never reach Cloudflare.",
      "cards": [
        ["Zero-configuration password", "shell <command> generates and prints a cryptographically random eight-character base64url browser password. The salted URL and password are both required; neither contains the derived encryption key."],
        ["Stronger custom password", "Eight generated characters provide 48 bits of entropy for convenient task-bound sharing. For sensitive or long-lived work, set a longer unique SHELL_ONLINE_E2EE_PASSWORD and send it separately from the complete URL when appropriate."],
        ["Local key derivation", "The URL contains only a random #salt= fragment. The CLI and browser derive the same AES-256-GCM key with PBKDF2-HMAC-SHA256 using 600,000 iterations. The relay receives neither password nor plaintext."],
        ["Protected and visible data", "Terminal input, output, snapshots, resizes, and latency probes are authenticated ciphertext. Cloudflare can still see connection IPs, timing, encrypted sizes, frame opcodes, access mode, labels, and lifecycle metadata."],
        ["Limits, recovery, and opt-out", "E2EE cannot hide traffic shape or prevent the relay from dropping, delaying, or replaying a valid encrypted frame. A lost password cannot be recovered. Anyone with both the complete salted URL and password can decrypt. The legacy --e2ee flag is redundant; --no-e2ee deliberately disables payload E2EE and is visibly labeled."]
      ]
    },
    "cli": {
      "eyebrow": "CLI reference",
      "title": "Every command and option, in one place.",
      "intro": "The shell CLI starts shares, reports their real relay state, attaches to local PTYs, and stops them. Run shell help reference to keep this complete reference available in the terminal too.",
      "cards": [
        ["Start and share", "Wrap a command in a local PTY and run it in the background. The URL prints after the relay exists and the task survives a short usability handshake. Fast exits report their status without a dead URL. With no command, shell starts $SHELL or /bin/sh. Put -- before the command when argument boundaries are ambiguous.", [["shell <command> [arguments...]", "Share a command in the background."], ["shell", "Share a fresh default shell."], ["shell -- <command> [arguments...]", "End shell.online option parsing explicitly."]]],
        ["Start options", "Options apply when a new share is created. E2EE is automatic unless explicitly disabled, and access mode cannot be weakened after creation.", [["--read-only", "Create an immutable view-only link; the relay rejects browser input."], ["--e2ee", "Compatibility flag; every normal share is already E2EE."], ["--no-e2ee", "Disable payload E2EE for compatibility/debugging; Cloudflare can relay plaintext. Conflicts with passwords and persistence."], ["--persistent <state-file>", "Reuse one stable encrypted identity, password, and URL."], ["--foreground", "Mirror and control the process in the launching terminal."], ["--auto-close <value>", "Add an earlier deadline; task exit remains the maximum lifetime. Missing or invalid values return status 2."], ["--json", "Emit the new-session event as JSON on stderr, including e2ee_password when encrypted."], ["--server <URL>", "Override the shell.online service URL."], ["--version", "Print the CLI version and exit."], ["-h, --help", "Print guided top-level help."]]],
        ["List sessions", "List locally managed processes and independently check the relay. The owner-only record retains the generated browser password so access can be shared again without replacing the session. Table states are online, starting, reconnecting, expired, and unknown; unknown means the check was inconclusive, not that the link died.", [["shell list", "Print ID, uptime, relay, closing rule, access, command, URL, and password."], ["shell list --json", "Print a JSON array on stdout with e2ee_password and raw relay_status values: connected, waiting, disconnected, expired, or unknown."]]],
        ["Attach locally", "Attach to an existing local PTY without disabling browser access. IDs may be complete or unambiguous prefixes of at least six characters. Local input and resulting output remain visible online. In a browser, the first Ctrl-D warns; repeat it within three seconds to deliberately send EOF.", [["shell attach <ID>", "Attach to one local session."], ["Ctrl-X, then D", "Detach while leaving the process and share running."], ["Ctrl-]", "Legacy detach alternative; Ctrl-Z is not detach."], ["Browser Ctrl-D twice", "Send a confirmed EOF; the first press alone never reaches the process."]]],
        ["Stop sessions", "Stopping sends termination to the wrapped process and closes its browser session. Completed tasks already close themselves automatically.", [["shell kill <ID>", "Stop one session by full ID or unambiguous prefix."], ["shell kill --all", "Stop every locally managed shell.online process."], ["shell stop <ID>", "Alias for shell kill."]]],
        ["Help and aliases", "Guided help is built into the executable, including this full reference. Command aliases do not change behavior.", [["shell help", "Show the guided workflow and common options."], ["shell help <topic>", "Topics: start, attach, list, kill, e2ee, docker, reference."], ["shell help e2ee", "Explain default encryption, passwords, and visible metadata."], ["shell help docker", "Explain persistent container state and password rotation."], ["shell help reference", "Print the complete built-in CLI reference."], ["shell ps", "Alias for shell list."], ["shell run / shell share", "Help-topic aliases for start; starting a process remains shell <command>."]]],
        ["Auto-close grammar", "A share always closes when its task exits. --auto-close requires a value and can only add an earlier deadline. Spaced multi-token dates are accepted directly. A missing or invalid value returns status 2 and never becomes the command.", [["5m · 2h · 3d · 1w · 2mo · 1y", "Relative units: ms, s, m, h, d, w, mo, and y."], ["1h30m · 2d 3h", "Compatible relative units can be combined, with or without spaces."], ["tomorrow 09:00 · today 18:30", "Natural local-day forms may be unquoted."], ["2026-09-01 14:30 · RFC3339", "Local ISO-like dates and full RFC3339 timestamps."], ["HH:MM", "The next occurrence of that local time."]]],
        ["Environment", "Only public configuration variables are listed here. Private background-handshake variables are internal implementation details and are not supported configuration.", [["SHELL", "Program used when shell is run without a command on Unix; Windows prefers PowerShell, then COMSPEC."], ["SHELL_ONLINE_SERVER", "Default relay URL; overridden by --server."], ["SHELL_ONLINE_E2EE_PASSWORD", "Override the generated eight-character password with a longer unique password; derivation remains local."], ["SHELL_ONLINE_INSTALL_DIR", "Installer-only absolute writable destination for the shell binary."]]],
        ["Output and exit status", "Normal starts show an animated connection state, then print a compact colored card after the task survives the startup handshake. A task that exits during that handshake prints its real status and no URL, attach, or kill instruction. Animation and color are disabled for JSON, pipes, NO_COLOR, and non-TTY output. Structured starts emit one JSON event on stderr so the wrapped process keeps stdout.", [["e2ee_password", "Present for encrypted sessions; agents must send it with the complete share_url. Omitted for --no-e2ee."], ["0", "Successful start or a fast task that itself exited successfully."], ["1", "Operational failure such as relay, process, or local-control failure."], ["2", "Invalid flags, arguments, or auto-close value."], ["shell list --json", "Structured session arrays are written to stdout; start --json events are written to stderr."]]]
      ]
    },
    "platforms": {
      "eyebrow": "Platforms and devices",
      "title": "From Windows workstations to ARM and MIPS routers.",
      "intro": "Each advertised target gets a real PTY implementation, background execution, local session management, E2EE, persistent identity, and a SHA-256-verified release artifact. Every Linux artifact executes the full Go and PTY integration suite under QEMU; Windows uses the native ConPTY API.",
      "cards": [
        ["Install", "The POSIX installer selects from the release manifest using uname. Windows uses a checksum-verifying PowerShell installer. Neither installer invokes sudo or silently edits PATH.", [["curl -fsSL https://shell.online/install | sh", "macOS, Linux, BSD, and Solaris."], ["irm https://shell.online/install.ps1 | iex", "Windows PowerShell on x86, x64, or ARM64."], ["https://shell.online/downloads/SHA256SUMS", "Canonical checksums for every binary and installer."]]],
        ["Support matrix", "Static release artifacts are built from one versioned target manifest and verified before deployment. Linux targets are runtime-tested under QEMU; native Windows amd64 is runtime-tested; the remaining targets are explicitly build-verified.", [["macOS · build-verified", "amd64, arm64"], ["Windows · amd64 native; others build-verified", "386, amd64, arm64"], ["Linux · QEMU runtime-tested", "386, amd64, armv5, armv6, armv7, arm64, loong64, mips, mipsle, mips64, mips64le, ppc64, ppc64le, riscv64, s390x"], ["FreeBSD · build-verified", "386, amd64, armv7, arm64"], ["OpenBSD · build-verified", "386, amd64, armv7, arm64, ppc64, riscv64"], ["NetBSD · build-verified", "386, amd64, armv7, arm64"], ["DragonFly BSD · build-verified", "amd64"], ["Solaris · build-verified", "amd64"]]],
        ["What QEMU proves", "Every Linux release binary executes its complete Go suite under the corresponding QEMU user-mode emulator. The suite covers executable startup, CLI help, E2EE, networking, persistent state, local session control, and a real PTY round trip with input and resize. QEMU cannot reproduce vendor firmware restrictions, a specific kernel configuration, or physical CPU errata."],
        ["Windows is native", "Windows sessions use ConPTY for ANSI/VT fidelity and an owner-restricted named pipe for list, attach, kill, and local takeover. Background startup uses an authenticated loopback handshake. PowerShell is preferred when no command is supplied, then COMSPEC."],
        ["Routers and small Linux devices", "The Linux binaries are CGO-free and include ARMv5 through ARM64 plus big- and little-endian MIPS variants. This covers many OpenWrt and Ubiquiti-style devices when their kernel exposes PTYs and outbound HTTPS/WebSockets. Check uname -m and available storage before installing; vendor firmware may still impose its own execution restrictions."],
        ["ROS 1 and ROS 2", "shell.online transports terminal bytes, so ROS needs no plugin or protocol shim. Source the ROS environment first, then wrap roscore, roslaunch, ros2 run, ros2 launch, colcon build, or a node with the normal shell command. ROS itself supports fewer OS/architecture pairs than shell.online; follow the compatibility table for the ROS distribution you installed."],
        ["One link across restarts", "Normal shares already run in the background. --persistent <state-file> stores an owner-only host identity, password, and E2EE material; rerunning with that file restores the same URL and password. The Docker image combines the same mechanism with restart: unless-stopped for automatic recovery after container or host restart. shell kill stops the current process without deleting the persistent identity file."]
      ]
    },
    "docker": {
      "eyebrow": "Persistent Docker terminal",
      "title": "One encrypted shell and one stable link across restarts.",
      "intro": "The Docker client keeps its workspace, host credential, browser password, E2EE key, and share identity in named volumes. Restart the container and the same browser URL reconnects to the new PTY.",
      "cards": [
        ["Start once", "Pull ghcr.io/teoslayer/shell.online:0.8.1 or run docker compose up --build -d, then docker compose logs shell-online. First launch prints the stable URL and a generated eight-character password. The tagged amd64/arm64 image includes an SBOM and build provenance."],
        ["Two durable volumes", "shell-online-state stores the browser password, host credential, share identity, and E2EE key. shell-online-workspace stores the container workspace. Treat the state volume and its backups as secrets."],
        ["Password continuity", "Set a longer SHELL_ONLINE_E2EE_PASSWORD only before first launch if desired. Restarts reuse the saved password. A conflicting configured password is refused; create a new state volume to rotate both password and URL."],
        ["Restart behavior", "The container reconnects the same relay identity and URL after a restart. Connected browser pages remain open and report offline until the host returns. An unused offline identity expires from the relay after 30 days but can be revived from its state volume."],
        ["What persistence is not", "This image is a persistent client for the hosted shell.online relay, not a self-hosted relay. It does not make the container immortal, publish ports, or recover a deleted volume or forgotten password."]
      ]
    }
  }
}