Content
# sshrew
<p align="center">
<img src="sshrew/assets/sshrew.png" alt="sshrew" width="220">
</p>
Let Claude reach any machine you'd normally SSH into. Claude can now read
files, tail logs, run allowlisted commands **without inbound SSH, port
forwarding, or config files.** Works on home servers, VPSes, Raspberry Pis,
Jetsons, whatever. If it runs Linux and can dial out, sshrew can bridge it.
## Quick start
On the machine you want Claude to see:
```bash
curl -fsSL https://raw.githubusercontent.com/duriantaco/sshrew/main/install.sh | bash
```
It prints:
```
==============================================================
Your bridge is live. In Claude, go to:
Settings -> Connectors -> Add custom connector
and paste this URL:
https://random-words.trycloudflare.com/kJx.../mcp
==============================================================
```
Paste that URL into claude.ai, enable the connector in a chat, done. By
default Claude can only read `~/.sshrew-share`; pass `--root DIR` when you
want to expose a specific project or log directory.
That one command handles everything: installs `uv` (which brings its own
Python 3.12, so old distros work), fetches sshrew, generates and saves a
secret token, downloads the right `cloudflared` binary for your CPU, opens
the tunnel, and starts the server.
## How it works
SSH is you reaching *in*. sshrew is the box reaching *out*:
```
claude.ai --(custom MCP connector)--> https://xxx.trycloudflare.com/<token>/mcp
|
cloudflared (outbound only)
|
sshrew on 127.0.0.1:8787
```
You need access to the machine exactly once — to run the installer. After
that (especially as a systemd service) you never reach in again.
The secret token lives in the URL path, so possession of the URL is the
credential. It's stored in `~/.config/sshrew/token`, reused across restarts,
and rotated with `--rotate-token`.
Every tool call is also recorded locally in `~/.config/sshrew/audit.jsonl`.
The log stores metadata like tool name, path, argv, exit code, bytes returned,
duration, and a token fingerprint. It does not store file contents, command
output, or the secret token itself. Ask Claude to call `recent_activity()` to
review what happened in the current session.
## Multiple machines
Run sshrew on each box. Each gets its own token and its own connector entry
("home-server", "lab-pi", "gpu-box"). Enable several in one chat and ask
Claude to compare across them.
## Options
Default is **read-only**, scoped to `~/.sshrew-share`.
```bash
sshrew --profile readonly # default: shared folder only
sshrew --profile dev # shared folder plus ~/projects and ~/src if present
sshrew --profile server # logs plus safe read-only diagnostics
sshrew --profile edge # server profile plus edge-device diagnostics
sshrew --profile full-trust # home directory plus unrestricted shell; be careful
sshrew --root ~/projects --root /var/log # narrow what Claude can read
sshrew --allow-shell --allow journalctl --allow systemctl
sshrew --allow-shell # full shell access; use only on trusted links
sshrew --no-tunnel # bring your own tunnel
sshrew --rotate-token # invalidate the old URL
```
Profiles are conservative. `dev` does not enable shell. `server`, `edge`,
`workstation`, and `ops` enable only a small read-oriented command allowlist.
`full-trust` is the only profile that grants unrestricted shell access.
Flags pass through the installer too:
```bash
curl -fsSL .../install.sh | bash -s -- --profile server
```
## Installing permanently
```bash
uv tool install --python 3.12 git+https://github.com/duriantaco/sshrew
sshrew
```
Run at boot with systemd. This installs the service for the current Linux user:
```bash
sed "s/^User=me/User=$USER/" sshrew.service | sudo tee /etc/systemd/system/sshrew.service >/dev/null
sudo systemctl daemon-reload && sudo systemctl enable --now sshrew
```
That user controls what sshrew can read and run. Keep it non-root.
Heads-up: **quick-tunnel URLs change every restart**, so a reboot means
re-pasting the connector URL. For a stable URL, point a named Cloudflare
tunnel or Tailscale Funnel at `127.0.0.1:8787` and run `sshrew --no-tunnel`.
The sample service includes systemd sandboxing and only allows writes to
`~/.config/sshrew` and `~/.sshrew-share`.
## Do I need nginx?
Not for the default setup. sshrew listens on `127.0.0.1`, and `cloudflared`
is the only public-facing network layer. nginx does not fix token leakage,
path scoping, or command execution risk.
Use nginx, Caddy, or a named Cloudflare Tunnel with Cloudflare Access if you
are directly exposing a stable domain and need TLS termination, request
limits, access logs, mTLS, SSO, or extra rate limiting.
## Roadmap
sshrew should be more than a tunnel. The goal is an agent-aware host capsule
for anything you can run: laptops, workstations, home servers, VPSes, lab
machines, Raspberry Pis, Jetsons, NAS boxes, CI runners, and edge devices.
Every machine gets explicit, inspectable rules for what an AI agent can see
or do.
- Capability tokens: mint separate URLs for separate roots, tools, and TTLs.
- Local approval queue: require terminal approval for risky operations like
service restarts, package installs, or writes.
- Audit controls: retention, export, tamper-evident hashes, and per-token
activity views.
- Profiles: per-profile command arguments, root templates, and generated
systemd services.
- Host facts: richer GPU, network, process, and service inventory.
- Device packs: optional tools for specific environments like NVIDIA Jetson,
Raspberry Pi, Docker hosts, systemd servers, macOS laptops, Linux laptops,
NAS boxes, and CI runners.
- Safer ops tools: expose `tail_logs`, `restart_service`, `docker_status`, and
`journal_errors` as structured tools instead of relying on raw shell.
- Stable URL wizard: generate named Cloudflare Tunnel, Tailscale Funnel, or
local-only configs from one command.
- Cloudflare Access mode: support service-token headers and JWT validation for
stable public deployments.
- Live dashboard: show current URL, roots, enabled tools, recent calls, and a
one-click token revoke.
- Event channels: push alerts when logs spike, thermals go high, disk fills, or
a watched service fails.
## Security notes
- The URL is the password. Long random token, never post it, rotate if in doubt.
- `--root` is a hard jail. Paths are fully resolved, including symlinks, and refused if they escape.
- Shell is off unless you pass `--allow-shell`. With `--allow CMD`, sshrew executes the parsed command directly instead of through a shell, so shell operators like `&&` and `|` are not executed. Without `--allow`, `--allow-shell` grants full shell access.
- sshrew runs with the permissions of its user. DO NOT run it as root.
- Reads are size-capped, negative offsets and sizes are refused, and binary files are refused.
- Search skips hidden directories and symlinks that point outside the allowed roots.
## Tools exposed
| tool | what it does |
|---|---|
| `list_dir(path)` | directory listing inside allowed roots |
| `read_file(path, offset, max_bytes)` | chunked text reads |
| `file_info(path)` | size / mtime / permissions |
| `search_files(root, name_glob, contains)` | recursive find + grep-lite |
| `run_command(command)` | shell, gated by `--allow-shell` / `--allow` |
| `host_facts()` | structured OS / CPU / memory / disk / service / device facts |
| `system_status()` | uptime, memory, disk (+ tegrastats if it's a Jetson) |
| `recent_activity(limit)` | recent audit log entries for accountability |
## License
MIT
