Connect a phone, browser, or another desktop app to styal running on a different machine. That machine must stay running and reachable while you work.
styal Link makes an environment available to your other devices without setting up router forwarding. In the desktop app on the host, open Settings → Connections, sign in, and enable styal Link for that environment.
For a command-line host, run:
npx @styal/cli@nightly linkFollow the sign-in instructions. Setup offers a
background service; if you decline it, start the
server with npx @styal/cli serve. Saving your sign-in alone does not make the
machine reachable.
On your other device, sign in to the same styal Link account and choose the environment. Over SSH, the CLI prints a browser link and a short code. Open the link on any device, confirm the code matches, and approve. The CLI continues on its own, so you do not need to forward an OAuth callback port.
styal Link renews access credentials when needed without disconnecting a healthy connection. Pull request diffs and provider settings keep working after the previous credential expires. A failed renewal affects that request; it does not disconnect an otherwise healthy conversation.
Use direct pairing when the other device can reach the host's network address.
On a desktop host, open Settings → Connections, enable Network access, then create a pairing link using an address the other device can reach. Changing network access restarts the desktop app. You can turn it off in the same place.
For a command-line host, replace <private-ip> with the host's LAN or tailnet
address:
npx @styal/cli serve --host <private-ip>If a server is already running, generate a fresh link without restarting it:
npx @styal/cli pairScan the QR code on your phone or paste the pairing URL into Add environment
in the receiving app. Connection settings are under Settings → Connections
on web and desktop and Settings → Environments on mobile. A loopback address
such as 127.0.0.1 reaches only the device opening the link.
Pairing authorizes that device for future connections. Use a fresh one-time link for each new device; you do not need the original token to reconnect. Links created in Settings can only be copied from the client that created them while its Connections page stays open. If you leave or reload that page, create another link to share.
Auto balance is off by default. On web and desktop, enable it in Settings → Connections → Load balancing to automatically choose a machine for new threads in projects grouped across connected environments. The section appears once two or more machines are switched on. Each machine starts at Normal. Choose Prefer to favor it when it has CPU and memory available, Less often to reduce its share, or Manual only to exclude it from automatic selection. These are preferences, not fixed traffic percentages. Preferences are saved separately in each client.
The composer checks eligible machines when choosing a draft's environment, then keeps that choice stable. Choose Auto balance again to check current resources, or choose a specific machine to override it. Choosing a branch or worktree also keeps the draft on that machine. Existing threads stay where they started. If resource checks are unavailable or all eligible machines are full, choose a machine manually to continue. Mobile keeps its manual environment selection.
Join both devices to the same tailnet. In the desktop app, enable Tailscale HTTPS in Settings → Connections. Turn it off there to remove that route.
To start a command-line server with Tailscale HTTPS:
npx @styal/cli serve --tailscale-serveFor an already-running server:
npx @styal/cli pair --tailscaleThe pairing link uses an address such as https://machine.tailnet.ts.net/.
The mapping created by pair --tailscale persists across restarts. Remove its
default-port mapping with:
tailscale serve --https=443 offIf that port is already in use, choose another with
--tailscale-serve-port. See npx @styal/cli pair --help for other pairing
options.
app.styal.build needs an HTTPS endpoint. It connects directly to your server; a hosted pairing link does not make an unreachable backend reachable or convert HTTP to HTTPS.
For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can
open it, or pair from the desktop app. On mobile, an IP address entered without a
scheme uses HTTP, so include https:// when your server uses HTTPS.
In the desktop app, open Settings → Connections → Add environment, choose
SSH, and enter a host or SSH alias such as user@example.com. styal starts
or reuses a server there and opens the port forward for you. Projects, provider
credentials, and agent work stay on the remote machine.
The remote host must be a macOS or Linux
supported platform with curl or wget, plus
provider setup. styal downloads the release matching
your desktop app to the host and verifies its checksum, so the host does not need
Node.js.
If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that styal launched; a server that was already running is left alone.
For Antigravity's Google callback on a remote host, see remote sign-in.
On the host, Settings → Connections lets authorized administrators create
pairing links and revoke client sessions. Revoking an unused link prevents new
pairings; revoke a device's session to remove its existing access. Command-line
management is available through npx @styal/cli auth --help.
A session with an open connection stays listed after its access credential expires.
To remove an environment from styal Link, open your account menu's styal Link page, or Settings → styal Link on mobile, and choose Deregister. This revokes its cloud access and frees its host space even when the environment is offline or has been wiped.
On a command-line host, styal link unlink disables exposure while retaining
your login; styal link logout also clears that login. Background-service
removal is separate.
Treat pairing URLs and authorization codes as passwords. Do not include them in screenshots, logs, or bug reports.
Run styal link status on the host to inspect saved authorization and link
configuration. It is not a live reachability check. If the environment appears
offline, run styal service status and read the displayed log. If it disappears
when SSH closes, see background-service troubleshooting.
| Error | Recovery |
|---|---|
environment_link_limit_exceeded or managed tunnel limit |
Deregister an unused environment, then restart styal on the host. |
auth_invalid or invalid_bearer |
Run styal link login. If credentials were revoked, run styal link logout, then styal link again. Restart the server after signing in. |
| Expired or invalid link proof | Check the host's date and time, update styal, then restart it. |
| HTTP 403 without a recognized error | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. |
| HTTP 408, 429, or 5xx | Check network and relay availability. Startup retries temporary failures for up to ten minutes. |
After fixing a permanent rejection, restart the host's server. On Linux, use
systemctl --user restart styal.service for the background service. For a
foreground server, stop it and run styal serve again with your usual options.
Include the diagnostic message and trace ID when reporting a persistent failure.
For a connection that still fails after linking, check the date and time on both devices. For server version warnings, follow Updating styal.
If a computer should only drive work running elsewhere, turn off its local environment. In the desktop app, open Settings → Connections and switch off Local environment. styal restarts without a local server: no local agents or terminals run, WSL backends stay off, and other devices can no longer connect to this computer. Your projects, history, and saved connections are kept, and you keep working through pairing, styal Link, or SSH.
Switch Local environment back on in the same place to restart with your previous local settings.