NAME

aude-rc — remote control of an aude session

SYNOPSIS

DESCRIPTION

Each session listens for clients: the iPhone app, the Mac app, and ‘aude attach’ on this machine or on another. Each client sends lines and sees the same transcript. The host of the session is the listener, and no other process runs.

The host listens on a free port of 127.0.0.1, or with --bind tailnet, of the Tailscale address of this machine. One host of each address also listens on the first free port from 8765 to 8772, where a device finds every session. When that host exits, another host takes its place.

A device must pair before it can attach. This machine and each device have a key, and the handshake makes each end prove its key.

Through any session that it reaches, a paired device can list the sessions of this machine, send a task to one, and start or remove a subagent. To keep this machine in reach of a phone, leave one session open with --bind tailnet. A host with no terminal exits when its input ends, so keep its input open; see EXAMPLES.

OPTIONS

--bind network

loopback, the default, is for this machine only. tailnet needs the Tailscale client.

--name name

The name of the session. The default is the name of the working directory. aude changes the name to lower case, changes each character that is not a letter or a digit to a hyphen, joins hyphens, removes hyphens at the two ends, and keeps the first 32 characters. An empty result is ‘aude’.

ATTACHING

When a session starts, its host prints the URL to attach to it:

Scan the QR code with the phone, paste the URL into the Mac app, or give it to ‘aude attach’ on another machine. The URL has no code, so only a device that has paired with this machine can use it; a device that has not paired is refused, and the URL is not a secret. See PAIRING.

PAIRING

‘aude pair [target]’ opens a pairing window on a running session for two minutes, and prints a URL:

Give the URL to the device: scan the QR code with the phone, paste the URL into the Mac app, or give it to ‘aude attach’ on another machine. The code is a secret, and it works one time only. ‘aude attach’ with the URL attaches one time and keeps no pairing.

In an app, New opens a sheet for the URL, and a link to the URL opens the sheet with the URL in it. The sheet shows the fingerprint of the device, and its button is Pair when the URL has a code, and Attach when it does not. When the text is not a URL the device can use, the button is off and the sheet says so under the text.

‘aude pair’ waits until a device pairs and prints ‘paired "<name>" <fingerprint>’, or until the window closes and prints ‘pairing closed’. A second ‘aude pair’ closes the first window.

A phone needs a session with --bind tailnet. The Mac app has its own key, so it must pair, also with a session on the same Mac.

DEVICES

‘aude devices’ prints the key of this machine first, then each listed device:

REVOKE

‘aude revoke device’ removes one device, by its name or by the start of its name or fingerprint. Its connections close within one second.

‘aude revoke --all’ removes each device and the key of this machine. Then each device must pair again, and each running session must start again.

THE KEY

The first command that needs a key makes it, and prints:

FILES

~/.aude/rc/device.key

The key of this machine, 32 bytes. Its mode must be 0600.

~/.aude/rc/peers.json

One JSON object from the fingerprint of each device that may attach to its name. A pairing writes it, and so may you, but not group or other.

EXIT STATUS

‘aude pair’ exits 0 when a device pairs, and 8 when the window closes or no session runs. aude(1) gives the other codes.

EXAMPLES

Serve this session to a phone:

$ aude --harness claude --bind tailnet
  <the QR code>
  aude-rc://100.64.0.1:8765#<fingerprint>

Serve a session with no terminal, until you stop it:

Pair the phone from a second terminal:

$ aude pair
  <the QR code>
  aude-rc://100.64.0.1:8765#<fingerprint>.<code>
  pairing window open for two minutes; it closes on the first pairing
paired "my phone" b7LEmcyVWf0iitc82uTqlBNbkx2CpRJJIkmg0FNEzU4

Remove the phone:

$ aude devices
this machine  uT6645vMT5l4Vlv9q1-cui2GPj_NEbQl9yxsJJYwlSg
my phone  b7LEmcyVWf0iitc82uTqlBNbkx2CpRJJIkmg0FNEzU4
$ aude revoke "my phone"
revoked "my phone" b7LEmcyVWf0iitc82uTqlBNbkx2CpRJJIkmg0FNEzU4

DIAGNOSTICS

A host that prints one of these lines exits 8 before its first turn. A client exits 8.

rc could not use this device's key file — <detail>

The detail tells the problem. When other users can read the file, run ‘chmod 600 ~/.aude/rc/device.key’. ‘aude revoke --all’ removes the file, and then each device must pair again.

could not attach — <name> is a name; use the address that aude pair printed

A host in a URL is an address.

could not attach — the handshake with <host> failed; it is not an aude host, or something between changed its bytes

The port is not an aude host, or a device between changed the bytes. Check the address; pairing again does not help.

rc could not read the peer list: <file> <defect>

The file is not one JSON object from fingerprint to name, names two devices alike, lists this machine, or is not a regular file only you write. A device that is attached stays attached, no other device can attach or pair, and aude does not change the file. Repair the file, or run ‘aude revoke --all’ (or remove the file) and pair each device again. Exit 6.

no tailnet address found (looked for 100.64.0.0/10 and fd7a:115c:a1e0::/48). Is the Tailscale client running?

Start Tailscale.

no session has a host — start one with: aude --harness <name>

‘aude pair’ found no running session.

<n> sessions are running: <names> — name one

Give ‘aude pair’ a target. Exit 64.

SEE ALSO

aude(1), aude-team(7), aude-terminal(7), aude-wire(7)

CAVEATS

A paired device can run shell commands on this machine as you, and nothing asks first. Pair only a device that you control, and revoke it when you do not.

Anyone who reads the URL while the window is open can pair. Do not show the URL to others, and check ‘aude devices’ after you pair.

Any process of your account can read the key, and a copy of the file is this device, on every platform. A backup holds a copy. With a copy, a person can attach to each host where this machine is a paired device, until that host revokes this machine.

Each end accepts only the key that it paired with. No certificate is used.

A host with --bind tailnet is not tested over a real tailnet.