# Your fleet on your phone (/docs/rlx/remote)

A fleet does not stop needing you when you leave the desk. An agent asks for
permission, the manager has a question, an account hits its usage limit. With
`rlx remote`, your phone shows one feed of everything waiting on you
across every project, each agent's live screen and conversation, and each
project's board. It notifies you when something new needs you, and, once you
allow it, lets you answer the prompt, tell an agent something, or stop,
restart or switch it.

This page is the reference for that phone remote. For the shortest path to
turning it on, and for Claude Code's own Remote Control, which is a different
thing, see [Control the fleet remotely](/docs/rlx/remote-control).

## How it works [#how-it-works]

Remote is one small web server on your machine, bound to `127.0.0.1:8750` and
nothing else. Your phone reaches it through your own ngrok tunnel, so nothing
is hosted anywhere else, and the page the phone loads ships inside
rlx. Every address sits under a secret link (a 32-character random
token in the path, and a 404 for anything without it), and the page asks for a
four-word password once per browser (the phone page calls it the passphrase).
Out of the box everything is **read-only**: the phone can look at everything
and change nothing until you allow writes.

Through `rlx` there is nothing extra to install. The web server, Web Push and
ngrok itself (the official ngrok Python SDK, running inside rlx) come
with rlx, and the one setup step is giving it your ngrok token, once.
Running Remote without the fleet UI needs the ngrok command-line agent as well: see
[Without the fleet UI](#without-the-fleet-ui).

## What a phone can do [#what-a-phone-can-do]

|                                                                      | Writes off (the default) | Writes on |
| -------------------------------------------------------------------- | ------------------------ | --------- |
| The Needs you feed, notifications, dismissing a card                 | ✓                        | ✓         |
| Every project's fleet, board, tasks and memory                       | ✓                        | ✓         |
| An agent's live screen and transcript                                | ✓                        | ✓         |
| Sign this phone out, turn its notifications on or off                | ✓                        | ✓         |
| Type into an agent or press keys on the pad, quick answers on a card |                          | ✓         |
| Post a note on the board                                             |                          | ✓         |
| Tell, stop, restart or switch an agent                               |                          | ✓         |
| Revoke another device, extend auto-off by an hour                    |                          | ✓         |

Tasks and Memory stay read-only on the page even with writes on: the page
offers no way to claim or finish a task, or add or remove a project. The
server is wider than the page, though. With writes on, it accepts a task claim
and done, a project switch, add or remove, a note, and keys typed into an
agent from any unlocked device, so treat allowing writes as giving every
signed-in phone those powers.

## Set it up [#set-it-up]

<Steps>
  <Step>
    ### Open Remote control [#open-remote-control]

    In `rlx&#x60;, open **⚙ Settings ▸ Remote control**. It opens *App settings* on its
    **Remote** tab. Pressing `R` in the sidebar opens the same Remote as a panel.

    
  </Step>

  <Step>
    ### Paste your ngrok token [#paste-your-ngrok-token]

    The first time, the tab asks for your ngrok token in place of *Turn on remote
    control*. Copy it from your ngrok dashboard (a free account has one), paste it
    under **Paste your ngrok token** and press **Save**. ngrok is asked whether it
    takes the token: one it refuses is said beside the field and not kept. A kept
    token is stored owner-only in `~/.aisquare/ngrok-authtoken` and never shown
    again.

    If you already use ngrok, there may be nothing to paste. rlx takes the
    first token it finds: `NGROK_AUTHTOKEN` in the environment you started `rlx`
    from, then the token saved here, then the one in your own ngrok config.
  </Step>

  <Step>
    ### Turn it on [#turn-it-on]

    Press **Turn on remote control**. The tab starts the server and ngrok, copies
    the link for you once ngrok announces it, and shows the link, a QR code and the
    password. Scan the QR code with your phone and type the password (spaces,
    dashes or capitals are all fine).

    
  </Step>

  <Step>
    ### Allow writes, if you want to act [#allow-writes-if-you-want-to-act]

    Open the tab's **Advanced** and switch on **Allow write actions**. From a
    shell, the same switch is:

    ```sh
    rlx remote allow-write on
    ```
  </Step>
</Steps>

The tab's **Advanced**, folded until you click it, holds the rest of the
controls: **Change ngrok token**, **Regenerate password**, **Allow write
actions**, the **Auto-off** timer (30, 60 or 120 minutes, or Never) and the
devices that have unlocked, with **Revoke selected**. The `R` panel has the
same controls but the ngrok token, over the same Remote: what one turns on,
the other shows on. It also has **New link** beside **Copy**: a new link and a
new password, so the old link stops opening and every device unlocks again.
While Remote is on, the sidebar shows `📡 remote · N devices`, and a click on
it opens the panel.

If ngrok stops, `rlx` starts it again. A Remote that was on when `rlx` closed
comes back on at the next start (unless its auto-off time passed meanwhile),
always with writes off. If ngrok later refuses the token Remote signed in with,
the token field comes back as **Replace your ngrok token**.

### Use a static domain [#use-a-static-domain]

Every ngrok account has one free static domain. With it, the link, the phone's
sign-in and a Home Screen app survive restarts; without it, the address
changes every time ngrok starts and the phone has to unlock again. Name it in
the environment you start `rlx` from:

```sh
export AISQUARE_REMOTE_NGROK_URL=https://your-name.ngrok-free.app
```

The bundled ngrok then serves on that domain, and notifications link to it.

### Without the fleet UI [#without-the-fleet-ui]

`rlx remote serve` runs the server alone, until Ctrl-C or auto-off. It does
not start a tunnel, and the ngrok inside rlx is a Python library with no
`ngrok` command, so this route needs the
[ngrok agent](https://ngrok.com/download) installed separately. The token you
pasted in `rlx` is kept in `~/.aisquare/ngrok-authtoken`, which the agent does
not read, so sign it in once with `ngrok config add-authtoken <token>`. Then
run it beside `serve`, in a second terminal:

```sh
rlx remote serve --auto-off 120 --public-url https://your-name.ngrok-free.app
ngrok http --url=your-name.ngrok-free.app --inspect=false 127.0.0.1:8750
```

Give ngrok `127.0.0.1:8750`, never `8750` alone: ngrok reads a bare port as
`localhost`, which is IPv6's `::1` first, where anyone on the machine could
listen and receive every phone's requests. Stop the ngrok when `serve` stops,
for the same reason; `serve` reminds you on its way out. On a machine others
use, also set `web_addr: false` in your `ngrok.yml`, so ngrok's local agent API
is off. Never run a second ngrok beside `rlx`'s: a static domain holds one
tunnel.

## Needs you [#needs-you]

The **Needs** screen is one feed, across every project, of what is waiting on
you, most urgent first. While a phone has the page open or notifications on,
the machine checks every 3 seconds.

What counts as needing you:

* **A permission prompt**: an agent waits for you to allow a tool, such as a
  Bash command or an edit.
* **A question** with options, or **a plan** to approve.
* **The manager asks, or reports a result**, on the board. So does a coder,
  when no manager is there to take it.
* **The manager is down**: it crashed, was killed, or its replacement did not
  start.
* **A crashed agent**, while no manager is there to handle it.
* **A usage limit**, with **Switch account** on the card.
* **A failed turn**: an API error such as an expired login or credit that ran
  out.
* **A lost pane**, or **tmux not answering** for a project.
* **A turn that ended with a question in plain text**, or an agent you
  interrupted that waits for you.

Each card carries what you need to read before answering: the exact command or
file a permission is for, every question with its options, the plan. Under it
sits the bottom of the agent's live screen, so the real option labels are next
to the buttons. **Quick answers** are checked against the agent as it is right
now: if the prompt has already gone, or the screen shows a different prompt,
the card says *No longer needs you* and nothing is typed. Anything without a
quick answer (one of Claude Code's own dialogs, a form) is answered from the
agent's key pad. `rlx remote needs` prints the same list on the machine.

## Notifications [#notifications]

On the phone, open **Settings ▸ Turn on**, then **Send test** to check the
whole path. A notification goes out when an item has stood for two scans, once
per item. Kinds that often clear by themselves wait a little first: a crash 30
seconds, a lost pane, a stopped manager or tmux not answering a minute, and an
interruption 10 minutes, since it follows your own Esc. A usage limit is never
pushed when it lifts within `wait_if_reset_within_minutes`, and waits 90
seconds when the fleet can switch the agent to another account by itself or a
live manager is on it.

**A notification never holds anything from an agent.** It is built from fixed
sentences (`coder-auth asks you a question`) with every name cut to 40
characters, plus a link to the card. No command, no question text, no excerpt.
The payload is encrypted to your browser's own key, so the push service sees
only that a message went.

* **iPhone and iPad (iOS 16.4 or later):** notifications work only from the
  page added to the Home Screen (Share ▸ Add to Home Screen) and opened from
  there. The Home Screen app has its own sign-in, so unlock it once more; it
  shows as a second device.
* **Android, and desktop Chrome, Firefox and Edge** need no install.

The machine also warns 10 minutes before auto-off, says goodbye when Remote is
turned off, alerts you when someone is guessing the password, and warns a day
before a phone's sign-in ends.

## Act on an agent [#act-on-an-agent]

Open an agent to see its **Live** screen (colours included) and its
**Transcript** (the conversation, wrapped to the phone). With writes on, the
input bar and key pad type into it, and its &#x2A;*Actions…** menu offers:

* **Tell**: one message, typed when the agent is waiting at its prompt,
  otherwise left as a board note it reads next. **Interrupt & tell** presses
  Esc first and types once the agent is back at its prompt.
* **Stop**, **Restart** and **Switch account**: each opens a sheet that says in
  one sentence what will happen. Restart and switch resume the agent's own
  session, and can take up to 40 seconds; the page waits and shows the result
  even if the phone slept meanwhile.

Safety rails are built into every action. Stopping types `/exit` and Enter,
and an Enter into an open dialog would answer it, so stop, restart and switch
are refused while the agent shows a prompt; the sheet offers **Press Esc (No)
first**. Every action is pinned to the agent you looked at: if the manager
restarted it meanwhile, the action is refused as stale rather than applied to
the replacement. Ctrl-C and Ctrl-D on the pad ask first, because Claude Code
exits on them. If nothing has arrived for 25 seconds, the page greys out and
holds every action until it is current again.

## The board [#the-board]

Each project's **Board** shows its newest events first, with a composer for a
note, a decision, a question or a result (a write). **Fleet** lists every
agent and its state, and **Tasks** and **Memory** are read-only.

## The security model [#the-security-model]

* **A secret link.** Every path is under `/r/<token>/`, a 32-character random
  token. Anything else is a 404, so the address leaks nothing, and the page
  sends no referrer.
* **A password.** Four distinct words from a list of 512, typed once per
  browser. Unlocking is limited to 5 attempts a minute per client and 20
  failures in 30 minutes across everyone; past that, new unlocks pause and
  subscribed phones get an alert.
* **Read-only by default.** Every write is refused until you switch **Allow
  write actions** on or run `rlx remote allow-write on`, and a Remote
  that `rlx` brings back at its start always comes back with writes off.
* **Every write is audited** in `~/.aisquare/remote-audit.log` (owner-only),
  one line per write. Typed text is recorded as a length; a tell keeps its
  first 120 characters.
* **Auto-off.** `serve` turns Remote off after 60 minutes by default
  (`--auto-off`, a week at most, `0` for never); `rlx` offers 30, 60 or 120
  minutes, or Never. With writes on, a phone can extend it an hour at a time,
  up to 8 hours ahead. `rlx`'s **Turn off** and auto-off sign every phone
  out. **Ctrl-C on `rlx remote serve`, or quitting `rlx`, signs none
  out**: each phone stays signed in until its own expiry and gets straight back
  in at the next `serve` on the same link. To cut phones off, run
  `rlx remote revoke --all`.
* **Devices.** Each browser that unlocks is a device: signed in for 7 days, and
  signed out after 24 hours unused. `rlx remote status` lists them;
  `rlx remote revoke <id>` drops one, `--all` drops every one.
* **A leaked link or password.** In the `R` panel, **New link** replaces the
  link and the password, so the old link stops working everywhere and every
  device unlocks again; **Regenerate**, beside the password, replaces the
  password alone. From a shell, `rlx remote regenerate-password` makes a new
  password and signs every device out, and `--new-link` also replaces the
  link.
* **Nothing from another origin.** ngrok carries the traffic and, for an HTTP
  endpoint, terminates its TLS. Beyond that, the page loads nothing from another origin and is served
  with a strict Content-Security-Policy and no framing. Every write and live
  connection must come from the page's own origin. The ngrok inside rlx
  has no traffic inspector and no local agent API, so nothing on the machine
  can read or drive the tunnel; a hand-started ngrok needs `--inspect=false`
  for the same reason.

## Commands [#commands]

| Command                             | What it does                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rlx remote serve`                  | Run Remote without the fleet UI until Ctrl-C or auto-off. `--port` (default 8750, `AISQUARE_REMOTE_PORT`), `--auto-off MINUTES` (default 60, `0` never, `AISQUARE_REMOTE_AUTO_OFF`), `--public-url URL` (the https address for links in notifications, `AISQUARE_REMOTE_NGROK_URL`), `--dist DIR` (serve another build of the page). |
| `rlx remote status`                 | Whether Remote is on for this machine, the link, the password, the devices and failed unlocks. `--port` for the link of a `serve` on another port.                                                                                                                                                                                   |
| `rlx remote allow-write on` / `off` | Turn the write actions on or off, for the running server and the next one.                                                                                                                                                                                                                                                           |
| `rlx remote regenerate-password`    | A new password; every device unlocks again. `--new-link` also replaces the link; `--port` as for `status`.                                                                                                                                                                                                                           |
| `rlx remote revoke <device-id>`     | Sign one device out; `--all` signs every device out and leaves Remote on.                                                                                                                                                                                                                                                            |
| `rlx remote needs`                  | What needs you right now, across every project, as the phone's feed shows it.                                                                                                                                                                                                                                                        |
| `rlx remote install-page <dist>`    | Install another build of the page over the bundled one (it lands in `~/.aisquare/remote-dist`).                                                                                                                                                                                                                                      |

The reporting commands take the global `--json` (`rlx --json remote needs`).

## Troubleshooting [#troubleshooting]

**The tab keeps asking for a token, or says ngrok did not take it.** ngrok
refused the token, or it was reset on ngrok's dashboard. Copy it again and
paste it under **Replace your ngrok token** (or **Advanced ▸ Change ngrok
token**). While `NGROK_AUTHTOKEN` is set in the environment `rlx` started
from, ngrok signs in with that one instead, and a line under the field says so.

**The phone shows ngrok's warning page, or notifications will not turn on.**
ngrok's free plan shows a warning before a tunnel's first page. Pass it, then
reload once.

**Every write says `bad_origin`.** Something between the phone and the server
rewrote the `Host` header, as ngrok's `--host-header=rewrite` does. Start ngrok
without it.

**`serve`, or the Remote tab, says another Remote is on.** One `~/.aisquare`
serves one Remote: another `rlx` or a `serve` in another shell has it. Turn
that one off, or use it.

**`serve` says the port is in use.** Something else took 8750. Pass `--port`
and give ngrok, and `status`, the same port.

**A hand-started ngrok says `--url` is an unknown flag.** That ngrok is too
old for static domains. Run `ngrok update`.

**The page says Remote is off on the machine, or the link changed.** Remote was
turned off, auto-off passed, ngrok came back on a new address, or the link was
regenerated. Turn it on again, or open the link the machine shows now.

**`rlx upgrade` warns, or `rlx uninstall` refuses, while Remote is
on.** They name the Remote that holds this machine. Turn it off first: an
upgrade would leave it running the old release, and an uninstall would leave it
running with nothing to turn it off.

**You installed another page build and want the bundled one back.**
`rm -rf ~/.aisquare/remote-dist`.

<Cards>
  <Card title="Control the fleet remotely" href="/docs/rlx/remote-control" description="The short path to your phone, and Claude Code's own Remote Control per role." />

  <Card title="Accounts and usage" href="/docs/rlx/accounts" description="What a usage limit does, and why Switch account works." />

  <Card title="The board" href="/docs/rlx/board" description="The same board, at the desk." />
</Cards>
