lwis docs

Agents / Remote machines and containers

Remote machines and containers

Your agent doesn't have to run on the computer in front of you. lwis works the same on an SSH devbox, a VM, a cloud workstation or a container. lwis only makes outbound HTTPS connections and opens no port, so nothing needs to reach the machine from outside.

Install over SSH

In your SSH session, run the same commands as on a laptop:

curl -fsSL https://lookwhatisee.xyz/install.sh | sh
lwis setup claude                 # if the agent is Claude Code
lwis install-service --enable     # the daemon as a systemd user service

A systemd user service stops when your last login session on the machine ends. On a server you log out of, let it keep running:

sudo loginctl enable-linger "$USER"

Pair your phone with it

The machine has no screen to scan, so print the link instead:

lwis pair --label devbox-eu --print-url

Open the link on your phone, or paste it under Machines in the app or the web app. Check that both sides show the same 6-digit code, then answer y in the SSH session. The machine then appears on your phone as devbox-eu, with its attached sessions.

The link works once and expires after 10 minutes. Send it only to your own device, never through a chat, a ticket or a shared log.

An agent that pairs its machine itself

An agent on a remote machine (a cloud workstation, a long-lived CI runner) can run the pairing for you:

  1. The agent runs lwis pair --label <name> --print-url and shows you the link.
  2. You open it on your phone, and you both compare the 6-digit code: the agent reads its own from the command's output.
  3. Only once you say the codes match, the agent confirms with lwis devices confirm <code>.

The code check is what makes this safe: someone who copied the link from the transcript would get a different code, and you wouldn't confirm it. If you can't compare the codes, don't pair.

Root shells and containers

The daemon keeps its socket in a private runtime directory, $XDG_RUNTIME_DIR/lwis, owned by you and with mode 0700. There is no /tmp fallback. In a root shell, over su, or in a container, XDG_RUNTIME_DIR is often unset, and lwis stops with the fix. For user id 0 it is:

mkdir -p -m 700 /run/user/0 && export XDG_RUNTIME_DIR=/run/user/0

Run lwis setup claude from a shell where this is set: the plugin then calls lwis with that runtime directory, whatever Claude Code's environment says. --runtime-dir or LWIS_RUNTIME_DIR selects another directory, which must pass the same checks.

Containers without systemd can run the daemon in the foreground instead: lwis up.

No lwis on the machine?

Share links work for any agent that can run curl and openssl, with nothing installed and nothing paired. Each link opens once, within 30 minutes.