{"id":48719907,"url":"https://github.com/shellrelay/runner","last_synced_at":"2026-04-24T05:01:37.580Z","repository":{"id":350717512,"uuid":"1208002199","full_name":"ShellRelay/runner","owner":"ShellRelay","description":"ShellRelay runner — connect any machine to ShellRelay for browser-based terminal access","archived":false,"fork":false,"pushed_at":"2026-04-17T04:17:29.000Z","size":72,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T05:37:31.768Z","etag":null,"topics":["cli","docker","go","pty","remote-access","shell","terminal","websocket"],"latest_commit_sha":null,"homepage":"https://www.shellrelay.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShellRelay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T17:29:01.000Z","updated_at":"2026-04-17T04:16:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ShellRelay/runner","commit_stats":null,"previous_names":["shellrelay/runner"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/ShellRelay/runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShellRelay%2Frunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShellRelay%2Frunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShellRelay%2Frunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShellRelay%2Frunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShellRelay","download_url":"https://codeload.github.com/ShellRelay/runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShellRelay%2Frunner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32209895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","go","pty","remote-access","shell","terminal","websocket"],"created_at":"2026-04-11T19:12:50.579Z","updated_at":"2026-04-24T05:01:37.569Z","avatar_url":"https://github.com/ShellRelay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ShellRelay Runner\n\nLightweight Go binary that connects any machine to [ShellRelay](https://www.shellrelay.com) for browser-based terminal access. No VPN, no SSH keys, no port forwarding.\n\n## The Problem\n\nGetting terminal access to a remote machine is harder than it should be.\n\nThe traditional approach — SSH — requires open ports, firewall rules, and distributed key management. On machines behind NAT, corporate firewalls, or cloud security groups that restrict inbound traffic, SSH often isn't an option at all. For Docker containers, you need access to the host first. For team environments, sharing SSH credentials is a security risk.\n\nThe result: engineers spend time fighting infrastructure just to reach a machine.\n\n## The Solution\n\nShellRelay flips the connection model. Instead of you connecting *in* to the machine, the machine connects *out* to the relay. Your browser then connects to the relay — and the relay bridges the two.\n\n- No inbound ports required\n- No SSH keys to generate or distribute\n- No VPN to configure\n- Works through any firewall, NAT, or cloud security group\n- Access any machine, Docker container, or Kubernetes Pod from any browser, anywhere\n- iPad and iPhone support coming soon\n\nThe runner is a single static binary. Install it, register the server once, and it is accessible from [shellrelay.com](https://www.shellrelay.com) immediately.\n\n**Security:** ShellRelay acts as a relay only. Terminal data is encrypted in transit (TLS) and never stored on ShellRelay servers. Session recordings are saved exclusively on your local machine. Each server authenticates with a unique token (`sr_*`) that you control and can rotate at any time.\n\n## 30-Second Demo\n\n![ShellRelay demo](demo.svg)\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/ShellRelay/runner/main/install.sh | bash\n```\n\nOr download a binary from [Releases](https://github.com/ShellRelay/runner/releases).\n\nSupported platforms: **macOS** (arm64, amd64) · **Linux** (arm64, amd64)\n\n## Quick Start\n\n### Option A — Interactive menu (recommended)\n\nJust run the binary with no arguments:\n\n```bash\nshellrelay\n```\n\nAn interactive menu launches. Use arrow keys or number keys to navigate.\n\n### Option B — Command line (runner-first)\n\n1. Register your server — generates a claim token, saves credentials, and starts the daemon:\n\n```bash\nshellrelay announce --email you@gmail.com \u003cserver-id\u003e\n```\n\n2. Log in to [shellrelay.com](https://www.shellrelay.com) and claim the server using the token printed above.\n\nThat's it. The daemon is already running and ready to accept connections.\n\n### Option C — UI-first (register in dashboard, then run)\n\n1. Log in to [shellrelay.com](https://www.shellrelay.com) and create a new server from the dashboard.\n2. Copy the connect command shown — it looks like:\n\n```bash\nshellrelay start \u003cserver-id\u003e \u003ctoken\u003e\n```\n\n3. Run it on your machine. Credentials are saved and the daemon starts immediately.\n\n## Interactive Menu\n\nRunning `shellrelay` (or `shellrelay menu`) launches a full interactive menu:\n\n```\n╔══════════════════════════════════════════════════╗\n│                    ShellRelay                    │\n╠══════════════════════════════════════════════════╣\n│       1. Register server with Gmail account      │\n│       2. Start daemon                            │\n│       3. Stop daemon                             │\n│       4. Restart daemon                          │\n│       5. Status                                  │\n│       6. Logs                                    │\n│       7. Sessions                                │\n│       8. Rotate token                            │\n│       9. Set relay URL                           │\n│      10. Upgrade to latest release               │\n│      11. Daemon install                          │\n│      12. Daemon uninstall                        │\n│      13. Version                                 │\n╠══════════════════════════════════════════════════╣\n│       0. Exit                                    │\n╚══════════════════════════════════════════════════╝\n\n  ↑↓ to move   Enter to select   q to quit\n```\n\n- Arrow keys or number keys (1–9) to select\n- Enter to confirm\n- `q` or `0` to exit\n\n## Docker\n\nBake the runner into any Docker image for instant browser terminal access:\n\n```dockerfile\nFROM ubuntu:24.04\n# ... your app setup ...\nCOPY --from=ghcr.io/shellrelay/runner /usr/local/bin/shellrelay /usr/local/bin/shellrelay\nCOPY --from=ghcr.io/shellrelay/runner /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint.sh\nENTRYPOINT [\"entrypoint.sh\"]\n```\n\n```bash\ndocker run -e SHELLRELAY_EMAIL=you@gmail.com \\\n           -e SHELLRELAY_SERVER_ID=my-container \\\n           myimage\n```\n\nThe container self-registers on startup. Check `docker logs` for the claim token, then claim it in the dashboard.\n\n## Commands\n\n```\nshellrelay               Launch interactive menu (default when no args)\nshellrelay menu          Launch interactive menu explicitly\n\nshellrelay start         Start as a background daemon\nshellrelay stop          Stop the daemon\nshellrelay restart       Restart the daemon\nshellrelay status        Check if the daemon is running\nshellrelay logs          Tail daemon logs (-f to follow, -n \u003clines\u003e)\nshellrelay run           Run in foreground (no daemon)\n\nshellrelay announce      Self-register with the relay (generates claim token)\nshellrelay rotate        Rotate the server token and restart\nshellrelay relay         Set a custom relay server URL and restart\nshellrelay sessions      List saved session recordings (asciicast)\nshellrelay upgrade       Download and install the latest release\nshellrelay daemon        Register/remove login service (launchd/systemd)\n\nshellrelay version       Print version\nshellrelay help          Show usage\n```\n\n### announce\n\nSelf-registers this machine with ShellRelay. The runner generates its own token and sends it to the relay. You then claim the server in the dashboard.\n\n```bash\nshellrelay announce --email you@gmail.com \u003cserver-id\u003e\nshellrelay announce --email you@gmail.com --name \"My Server\" \u003cserver-id\u003e\n```\n\nRunning announce again on the same server ID prints the saved token — useful if you need to reclaim.\n\n### relay\n\nSets a custom relay URL, saves it to config, and restarts the daemon if running.\n\n```bash\nshellrelay relay --url wss://your-relay.example.com\nshellrelay relay --url your-relay.example.com   # wss:// prepended automatically\n```\n\n### daemon\n\nRegisters or removes the runner as a login service (auto-starts on reboot):\n\n```bash\nshellrelay daemon install    # macOS: launchd, Linux: systemd\nshellrelay daemon uninstall\n```\n\n## Configuration\n\nConfig is stored at `~/.shellrelay/config`:\n\n```\nSHELLRELAY_SERVER_ID=my-macbook\nSHELLRELAY_TOKEN=sr_xxxxxxxxxxxxxxxxxxxx\n# SHELLRELAY_URL=wss://your-custom-relay.com   (optional, set via: shellrelay relay --url \u003curl\u003e)\n```\n\nThe relay URL defaults to `wss://prod-api.shellrelay.com` (compiled into the binary). Override with:\n\n- `shellrelay relay --url \u003curl\u003e` — persists to config, restarts daemon automatically\n- `--relay \u003curl\u003e` flag on `start` or `run`\n- `SHELLRELAY_URL=\u003curl\u003e` environment variable\n\nPriority: `--relay` flag \u003e `SHELLRELAY_URL` env \u003e `~/.shellrelay/config` \u003e compiled-in default\n\n## Build from Source\n\n```bash\ngit clone https://github.com/ShellRelay/runner.git\ncd runner\ngo build -ldflags \"-s -w -X main.Version=$(cat VERSION)\" -o shellrelay ./cmd/shellrelay\n```\n\n## How It Works\n\n1. The runner opens a WebSocket connection to the ShellRelay relay server.\n2. When you click **Connect** in the dashboard, the relay bridges your browser to the runner.\n3. The runner spawns a PTY (pseudo-terminal) and streams I/O over the WebSocket.\n4. Sessions are recorded locally as [asciicast](https://docs.asciinema.org/manual/asciicast/v2/) files — they never leave your machine.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Security Policy](SECURITY.md)\n- [Report a Bug](https://github.com/ShellRelay/runner/issues/new?template=bug_report.md)\n- [Request a Feature](https://github.com/ShellRelay/runner/issues/new?template=feature_request.md)\n\n## License\n\n[MIT](LICENSE)\n\nCopyright 2025-2026 ShellRelay\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellrelay%2Frunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshellrelay%2Frunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshellrelay%2Frunner/lists"}