#Use crabcode away from your keyboard

crabcode can run on one machine while you control it from another. The machine with the project checkout, credentials, tools, and session history is the host. Your phone, tablet, or second laptop is a client.

That shape covers two common cases:

The main idea is:

# Host machine
crabcode serve

# Browser client
# Open the URL printed by the host.

# Terminal client
crabcode attach <url-or-alias>

# One-shot remote prompt
crabcode -p --attach <url-or-alias> "continue the refactor"

For any URL that another device can reach, use pairing:

crabcode serve --paircode random

The host prints a short pair code. Enter it once from a browser or crabcode attach; the client stores a trusted token in its crabcode state directory so future attaches can use the remembered host alias.

#How remote usage works

crabcode serve starts a small HTTP host for the current workspace. The host owns the important things:

Clients are thin control surfaces:

crabcode does not expose a general remote shell or proxy arbitrary development ports. It exposes crabcode sessions. If your app also runs a dev server on the host, expose that separately through your LAN, Tailscale, SSH forwarding, or another preview tunnel.

#Same machine

The default bind address is local-only:

crabcode serve --paircode random

Open the printed browser URL on the same machine, usually:

http://127.0.0.1:8421

You can also attach from another terminal on the same machine:

crabcode attach http://127.0.0.1:8421

#Local network

To reach crabcode from a phone or another laptop on the same Wi-Fi or Ethernet network, bind the host to a reachable address.

On the machine with the project:

cd ~/code/my-project
crabcode serve --bind 0.0.0.0:8421 --paircode random

The host will print a phone URL when it can detect one. If it prints only 127.0.0.1, replace that address with the host machine's LAN IP, for example:

http://192.168.1.42:8421

From a phone or laptop browser:

1. Open the LAN URL.
2. Enter the pair code printed by crabcode serve.
3. Prompt, monitor, cancel, or switch sessions from the browser.

From another laptop terminal:

crabcode attach http://192.168.1.42:8421

After pairing, crabcode attach remembers the host. List remembered hosts with:

crabcode hosts

Then attach by alias:

crabcode attach my-project

--bind 0.0.0.0:8421 listens on every network interface. Use it only on networks you trust, keep the pair code enabled, and stop the host with Ctrl+C when you are done.

#External network with Tailscale

Tailscale works well with crabcode because it gives your devices private network reachability. crabcode does not need a Tailscale integration; it only needs to bind to an address your tailnet devices can reach.

Recommended shape:

1. Install Tailscale on the host machine and the client device.
2. Sign both devices into the same tailnet.
3. Start crabcode on the host, listening on all interfaces.
4. Copy the host's Tailscale IP or MagicDNS name.
5. Open http://<tailscale-ip-or-name>:8421 from your phone.

On the host:

cd ~/code/my-project
crabcode serve --bind 0.0.0.0:8421 --paircode random

From a phone browser:

http://<tailnet-ip>:8421

If you use MagicDNS, the URL can be a machine name instead:

http://devbox:8421

From another laptop:

crabcode attach http://devbox:8421

For a one-shot prompt:

crabcode -p --attach http://devbox:8421 "summarize the current state and keep going"

This is the "off grid for lunch" workflow: the project stays on your laptop, Mac mini, homelab box, or VPS, while your phone reaches it over Tailscale. Your provider credentials stay on the host.

For a tighter bind that listens only on the host's Tailscale interface, use the host's Tailscale IPv4 address:

TAILNET_IP=$(tailscale ip -4)
crabcode serve --bind "$TAILNET_IP:8421" --paircode random

Binding to 0.0.0.0 is usually the most convenient setup and still lets you connect through Tailscale, but it also listens on LAN interfaces. Keep the pair code enabled and stop the host with Ctrl+C when you are done.

#Choosing a server

The server is simply the device that owns the checkout and runs crabcode serve.

A VPS can join your tailnet like any other device. In that setup, Tailscale is the private network.

Do not expose a write-capable crabcode host directly to the public internet. Put it behind Tailscale, another private network, SSH forwarding, or a hardened access layer.

#Remote app previews

If crabcode starts or edits an app that runs on localhost:3000, remember that localhost means different things on different devices.

On the host machine:

http://localhost:3000

On your phone, that same URL points at the phone, not the host. Use one of these instead:

crabcode remote access controls crabcode. It does not automatically expose every dev server running on the host.

#Classic SSH remote usage

You do not need crabcode serve for the classic terminal workflow. This is how you would use many terminal coding agents remotely: SSH into the machine that has the project, start a persistent terminal session, and run crabcode there.

From another laptop:

ssh devbox
cd ~/code/my-project
tmux new -A -s crabcode
crabcode

If the SSH connection drops, reconnect and run the same tmux command:

ssh devbox
cd ~/code/my-project
tmux new -A -s crabcode

From an iPhone with Termius:

1. Add the host in Termius. Use a Tailscale IP, Tailscale hostname, or normal SSH hostname.
2. Connect over SSH.
3. Run cd ~/code/my-project.
4. Run tmux new -A -s crabcode.
5. Run crabcode.
6. Reconnect later and run tmux new -A -s crabcode again to return to the same terminal session.

This path has more friction on a phone because you are using a terminal UI through a mobile keyboard. It is still useful when you want the safest possible setup, when the browser client is not enough for a particular workflow, or when you already live in SSH.

#Current limits

Remote usage is personal-device oriented. It is not a shared team workspace or public hosted service.

Browser access is best for prompts, transcript review, session switching, model or agent changes, permission approvals, agent questions, and cancellation. For full TUI behavior from another laptop, use crabcode attach <url>. For the most conservative remote setup, use SSH with tmux and run normal crabcode.

Keep these defaults in mind: