Remote access

Phone pairing over Tailscale, approved devices, and paired computers.

Remote access lets you use pi-kit from your phone, and lets one pi-kit work on the projects of another computer. pi-kit publishes itself only on your own Tailscale network. Nothing is reachable from the public internet, there is no pi-kit account, and no traffic passes through a pi-kit server. A device can connect only after you approve it on the computer.

This is remote control of your own computer, not a hosted service. The computer must be awake and pi-kit's service running. With Keep running when pi-kit is closed on in Settings → General, or after pi-kit service install, it keeps running when the pi-kit window is closed.

Before you start#

Install Tailscale on the computer and on the phone, and sign both into the same tailnet.
Enable HTTPS certificates for the tailnet once in the Tailscale admin console. A tailnet administrator may need to approve this.
Make sure your tailnet rules allow the port you plan to use. The default is 8443.

Being on the same Wi-Fi is not enough. The phone must be connected to Tailscale. The short setup guide at remote.pi-kit.dev walks through these steps on the phone.

Turn on remote access#

Open Settings → Remote access. The Connection tab checks Tailscale and lists the remaining steps: connect Tailscale on this computer, approve HTTPS certificates, then enable access. Each row links to the matching Tailscale page.

Settings → Remote access before it is turned on. Tailscale is connected, HTTPS certificates are approved, and the port is still the default 8443.

Choose the HTTPS port and select Enable remote access. Port 443 gives an address without a port number. Once Tailscale confirms the mapping, the card shows Active and your private address, https://<computer>.<tailnet>.ts.net:<port>.

Remote access active on port 8446. The tailnet address is blurred in this image.

Without the desktop app, for example on a server, pi-kit remote enable, pi-kit pair and pi-kit devices do the same from a terminal. See Command line.

Opening Settings only reads Tailscale's status. pi-kit never runs tailscale up, down, funnel or reset, and never turns on Funnel. Disabling remote access stops the publication and leaves the VPN as it was.

Pair a phone#

Open the Approved devices tab and select Pair device. A dialog shows a QR code and a 12-character pairing code, valid for five minutes.
Scan the QR code with the phone's camera. Or open your private address followed by /phone and type the code.
On the phone, select Request access. The phone shows a six-digit confirmation code.
The same request appears in the dialog on the computer. Approve it only if both codes match.

The Pair device dialog with its pairing code. The QR code is blurred in this image because it contains the tailnet address.

The pairing request on the computer, with the phone's browser and the confirmation code. with Approve and Deny.

After approval the phone opens pi-kit at the private address. To keep it one tap away, open the address in Safari and choose Share → Add to Home Screen. iOS may give the Home Screen app its own storage. If it asks for pairing on first launch, pair it once more with a new code.

Use pi-kit on the phone#

The phone shows the same threads and projects as the computer. You can chat in existing or new threads, answer questions and approvals, choose models, browse files, review changes, use the terminal, and dictate with a voice model configured on the computer.

On the phone: the confirmation code after Request access, the thread list, and an open thread. Seeded demo profile, captured in the iOS Simulator.

Machine-level settings stay on the computer and do not appear in Settings on the phone. These include providers, local models, MCP servers, computer use, extensions, skills and project trust. Set them up on the computer first.

An approved device acts with your account on that computer, including its files and shell. Approve only your own devices. Remote access is not a way to share an agent with someone else.

Manage devices#

Approved devices lists every paired device with when it was paired and last seen. Revoke access ends its session at once. Approvals persist across restarts and when remote access is turned off and on again.

The Approved devices tab with one paired iPhone and its Revoke access button.

Changing the HTTPS port changes the address, so a Home Screen entry has to be added again.

Connect another computer#

Each pi-kit installation is an environment with its own name. A project belongs to one environment, and a thread always runs where its project lives. With a single computer, nothing changes.

To pair two computers, turn on remote access on both. Then open Settings → Remote access → Environments:

On the first computer, under Paired instances, select Create invitation (5 minutes) and copy the invitation.
On the second computer, paste it and select Request reciprocal pairing.
Both computers show the same code. Approve on both only if it matches.

Without the desktop app, pi-kit peers invite, pi-kit peers connect and pi-kit peers approve do the same. See Command line.

After pairing, the environment switch at the bottom of the sidebar lists both computers and their projects. Choosing a project on the other computer reloads pi-kit against it, and the switch shows whose files you are working on. You can also allow phones approved on either computer to use the pair. A phone can reach the other computer in a pair, but never a computer paired with that one.

Security#

The pairing code is single-use and expires after five minutes. A request expires after two minutes and needs your approval.
An approved phone holds a secure, HTTP-only session cookie and needs a per-page token on every request. pi-kit stores only a hash of the cookie.
Requests go through a gateway that accepts only the routes the phone app needs. Administrative routes, the embedded browser and MCP apps stay on the computer.
The pi-kit backend keeps listening on the local machine only. Its access token never appears in a QR code, a page or the phone's storage.
Computers pair with keys that the operating system's credential store protects. A machine without one can use an owner-only key file instead, turned on with pi-kit peers key-file --yes. A changed key or address requires pairing again.

Troubleshooting#

Symptom	What to do
Setup needed with an HTTPS link	Enable HTTPS certificates in the Tailscale admin console, then select Check again.
The port is already in use	Another Serve or Funnel mapping uses it. Choose another port; pi-kit does not overwrite existing mappings.
The phone cannot open the address	Connect the phone to Tailscale and check that the tailnet rules allow the port.
The phone shows the pairing page again	Its session cookie is gone or the device was revoked. Pair it again.
The other computer shows offline	It is asleep, its pi-kit service is not running, or its remote access is off.