Documentazione

How Scomp works

Scomp has three parts. A lightweight Go agent runs on your machine and discovers your active terminal sessions. It dials out to the relay (link.scomp.me) over an encrypted WebSocket. Your phone or browser connects to the same relay, authenticates with Google, and streams the terminal in real time. No inbound ports, no VPN, no SSH keys to hand out.

Before you start

• A machine running Linux or macOS (amd64 or arm64) with a terminal.
• tmux or screen installed — so your work survives disconnects. Most systems already have one; install with apt install tmux, dnf install tmux, or brew install tmux.
• A phone or second device with a modern browser and a Google account for sign-in.

Quick start

From nothing to controlling a terminal from your phone in six steps.

1. 01

   Install the agent (no root needed)

   Download the single static binary and drop it in ~/.local/bin. No sudo, no system directories, nothing to uninstall later — just delete the file.

   curl -fsSL https://github.com/smart-bit-me/scomp-agent/releases/latest/download/scomp-linux-amd64 -o scomp \
     && chmod +x scomp \
     && mkdir -p ~/.local/bin && mv scomp ~/.local/bin/scomp

   Make sure ~/.local/bin is on your PATH (it is by default on most modern Linux distros and macOS). If scomp isn't found, add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc or ~/.zshrc. macOS/arm users: swap the filename for scomp-darwin-arm64.

2. 02

   Start a persistent session (tmux or screen)

   Scomp relays existing terminal sessions — it doesn't spawn your work for you. Start your long-running task inside tmux or screen so it keeps running when you disconnect, close your laptop, or drop off Wi-Fi. This is the key habit: always run inside a session.

   # tmux — create and enter a named session
   tmux new -s work
   
   # …or screen, if you prefer
   screen -S work

   On Linux, Scomp can also discover raw kernel PTYs, so a plain terminal can be relayed too — but only tmux/screen survive a disconnect. For anything you care about, use one of them.

3. 03

   Run your long task inside the session

   Inside the session, launch whatever you want to babysit from your phone — an AI coding agent, a build, a deploy, a training run, a log tail.

   # examples of things worth watching from your phone
   claude                 # Claude Code — pauses for your approval
   npm run build          # a long build
   ./deploy.sh production # a deploy you want to confirm
   journalctl -fu myapp   # a live log tail

4. 04

   Detach and start the relay agent

   Detach from the session so your task keeps running in the background, then start the agent. It prints a banner with your UID, a QR code, and a URL.

   # detach:  tmux → Ctrl-b then d     |     screen → Ctrl-a then d
   
   # then start the relay agent
   scomp

   The agent dials out to the relay over an encrypted WebSocket — you never open an inbound port and never touch your firewall. Leave it running in a spare terminal (or under its own tmux window).

5. 05

   Connect from your phone

   Scan the QR code with your phone's camera (or open the printed https://link.scomp.me/?uid=… URL), sign in with Google, and tap your session — e.g. tmux:work. You're now watching and controlling that exact terminal, live, from anywhere.

   Your UID is stable (stored at ~/.config/scomp/uid), so once your phone is paired, reconnecting later is one tap.

6. 06

   Walk away — get pinged when needed

   Close the laptop and go. When your AI agent pauses for approval or the session falls silent after activity, Scomp sends a push notification. Reconnect, approve or type, and let it keep going.

tmux & screen cheat sheet

A persistent session is the foundation of everything Scomp does. Keep your long-running work in one and you can detach, walk away, and reconnect from any device without losing state.

Recommended workflow: babysitting an AI agent

The pattern Scomp was built for. Run a long AI coding session (Claude Code, or any agent that pauses for approval), then supervise it from your phone and approve steps as they come.

# 1. persistent session so the agent survives a disconnect
tmux new -s claude

# 2. start the agent inside it, then detach with Ctrl-b d
claude

# 3. start the relay (in another terminal or tmux window)
scomp

# 4. scan the QR on your phone, sign in, tap "tmux:claude"
# 5. get a push notification whenever the agent needs approval —
#    approve from your phone and it keeps going.

For supervised or sensitive environments, start the agent relay with --mode approved-only so every keystroke must be pre-approved at the agent level.

Session modes

Control how much a connected browser can do with --mode:

Hosted relay v0.4.x supports agent v0.2.4 and newer. Signed-in clients show a warning when a connected agent needs a security update. Use scomp --version to check locally.

Command-line reference

The agent stores a stable identity at ~/.config/scomp/uid; your connect URL is https://link.scomp.me/?uid=<uid>.

FAQ