# Phone companion > Connect your phone through Tailscale in Settings, read conversations, answer supported requests, and start work on your computer. The phone companion preview is a browser app for agents running on your computer. It shows their conversations and requests, and starts new conversations in the projects the phone can work in. The agent keeps running on the computer. - App: **Settings → Remote access → Connect a phone** - CLI: `hansard remote host link` For read-only archive browsing, use the [Hosted viewer](https://www.hansard.dev/sync/hosted-viewer/). For pairing two computers, see [Remote access](https://www.hansard.dev/sync/remote-access/). ## Connect with Tailscale The computer needs Hansard, signed-in agent CLIs, and a working [Tailscale](https://tailscale.com) connection. Keep it awake and connected to the network. A tailnet is the private network your Tailscale devices share. Hansard walks through these steps and draws what the phone and Tailscale's admin console show: select **Guided setup** beside **Connect a phone**, or open guided setup's **Remote access** guide and choose **A phone**. 1. Install Tailscale on the phone. 2. Sign the phone in to the same tailnet as the computer. 3. If MagicDNS is off, enable it on the Tailscale admin console's **DNS** page. 4. Under **HTTPS Certificates**, select **Enable HTTPS** for the tailnet. 5. On the computer, open **Settings → Remote access → Connect a phone**. 6. Select **Prepare phone access**. Hansard turns on remote access and checks Tailscale. If HTTPS is already ready, continue at **This phone can work in** below. 7. If a setup command appears, select **Copy command**. 8. Run the copied command in Terminal on the computer. The command starts with `tailscale serve --bg --https=443` and points to Hansard's local gateway. Use the port shown in the command. 9. Select **Check connection**. 10. Under **This phone can work in**, choose one: - **All projects on this computer** - **Projects in** a portfolio - **Only shared projects**, then check the projects under **Projects this phone can access** 11. Select **Create connection link**. 12. Scan the QR code with the phone's camera. 13. On the phone, enter **Name for this phone**. 14. Select **Connect**. 15. Add the page to the home screen with the browser's **Add to Home Screen** or **Install app** action. [Tailscale Serve](https://tailscale.com/kb/1312/serve) publishes the gateway only to devices on your tailnet, not to the public internet. Tailscale access rules still apply. Hansard generates the QR code locally. > **Keep the connection link private:** The connection link works once and expires after ten minutes. Anyone who > claims it can control agents in the projects the link names. Keep the link and > QR code private. These are the same choices as **Can work in** under **Allowed devices**, where you can change them after the phone connects. The phone does not need a new link. **Projects in** lists your portfolios. **Only shared projects** appears after you share a project with **Share a project**. The choice limits which conversations the phone sees and where new work starts. It does not restrict an agent's file access. The agent keeps its permissions on the computer. **Claude Code approvals on your phone** stays off until you turn it on in **Settings → Remote access**, after pairing a phone. When enabled, supported terminal approvals wait up to 15 seconds for the phone, then use the terminal prompt if no decision arrives. See [Tailscale's HTTPS setup](https://tailscale.com/kb/1153/enabling-https) for the admin console steps. HTTPS certificates publish the computer's Tailscale DNS name in a public certificate log. ## Connect without Tailscale Install Hansard and sign in to the agent CLIs on the host computer. Keep the computer awake and connected to the network. This path uses a tunwg relay that you or your administrator has already configured. Hansard does not provide a public relay. On the host computer: 1. Initialize the host: ```sh hansard remote host init --label "My computer" ``` 2. Register a project, replacing the example path with its absolute folder path: ```sh hansard remote host project example --cwd /path/to/project --label "Example project" ``` 3. Configure the relay, replacing the example hostname with your relay's hostname: ```sh hansard remote host relay --api relay.example.com ``` If the relay requires a credential, add `--auth-file `. 4. Turn on access: ```sh hansard remote host access on ``` 5. Check that the gateway has a working HTTPS address: ```sh hansard remote host access status ``` 6. Create a link for the registered project: ```sh hansard remote host link --projects example ``` Use a comma-separated list to include more registered projects. Replace `--projects example` with `--all` for every project folder on the computer, or with `--portfolio ` for one portfolio's projects. The command returns a `url`. The same ten-minute limit and one-use rule apply to this link. Keep the whole link private. On the phone: 1. Open the returned link in your browser. 2. Enter **Name for this phone**. 3. Select **Connect**. 4. Add the page to the home screen with the browser's **Add to Home Screen** or **Install app** action. See the [remote host reference](https://www.hansard.dev/reference/remote-host/) for relay requirements and CLI options. ## Use the phone app The phone app is for the agents running on your computer. | Tab | What you can do | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Agents** | See which agents are running and which need you. Select an agent to read its conversation and current state. | | **Inbox** | Review approvals and questions that the host can answer from the phone. | | **Search** | Find a message in any conversation the phone can open, or switch to **Titles** to match titles and projects. Select a match to open its conversation at that message. | | **Devices** | Review the connected computer and what the phone can work in, set reminders, or sign out. | Select **New conversation** (the plus at the top of a tab) to choose a **Project**, **Agent**, and **Model**, enter a task, and select **Start conversation**. Pull down at the top of **Agents** or **Inbox** to refresh them. Use **Load earlier messages** to read older conversation text. **Jump to latest** returns to new output after you scroll away. Send a message from the conversation when its composer is available. Open **Agent actions** for **Pause**, **Revive**, **Stop**, **Continue on phone**, and **Conversation details**. The host determines which controls work for that agent. An unavailable control explains why. Pausing an eligible idle terminal saves its conversation and closes that terminal run. Continuing an existing Hansard run takes control without restarting it. Approvals and questions appear only when the host supplies those controls. An agent visible in **Agents** may still need you at its original terminal. ## Add the app to your home screen Use your browser's **Add to Home Screen** or **Install app** action. The app loads conversations from the computer when connected. It does not store conversation history for offline reading. **Waiting reminders** works while the app is open, where the browser supports system notifications. Background push notifications are not connected. ## Native iOS source preview The source checkout includes a SwiftUI app in `mobile/ios/`. It displays this same phone page with native QR pairing, a paired Mac list, Keychain credentials, and a link share sheet. It can schedule local reminders while the app is active. It does not receive new events while suspended. The native app has simulator testing only. Signing and physical-device acceptance remain unfinished. There is no signed app, TestFlight download, or native Android app to download. Open `mobile/ios/README.md` in the source checkout for Xcode, iPhone signing, and TestFlight steps. The phone still needs the separate Tailscale app for a Tailscale gateway. ## Disconnect or revoke access Select **Devices → Sign out this phone** to sign out. Accepted work keeps running on the computer. On the host, remove the phone under **Settings → Remote access → Allowed devices** to revoke its access. Turning off **Allow access from other devices** disconnects devices and leaves accepted work running. Stop an agent separately when you want its work to end. ## Troubleshooting ### Tailscale setup messages Hansard checks the HTTPS configuration before offering a connection link. It leaves existing Tailscale Serve and Funnel configurations unchanged. | Message | Meaning and action | | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Turn off Funnel for this HTTPS name before using private phone access.** | Funnel makes this HTTPS name public. Turn off Funnel for this name before retrying phone setup. | | **A foreground Tailscale Serve command uses HTTPS. Finish it before configuring phone access.** | A running terminal command occupies HTTPS port 443. Finish that command in its terminal before retrying phone setup. | | **Tailscale Serve already uses HTTPS for another service. Its configuration has not changed.** | Port 443 has another service, extra routes, or a destination that differs from Hansard's gateway. Move that configuration away from port 443 before retrying phone setup. | | **Connect this computer to Tailscale to use phone access.** | Hansard cannot find a connected Tailscale device with a usable HTTPS name. Connect the computer to Tailscale. | | **This computer's Tailscale name changed. Set up phone access again.** | The current name differs from the saved HTTPS address. Repeat [Connect with Tailscale](https://www.hansard.dev/sync/phone-companion/#connect-with-tailscale) to create a link for the new name. | | **Tailscale Serve status is unavailable. Check the Tailscale installation.** | Hansard cannot read the Serve configuration. Check that Tailscale is installed and running on the computer. | If **Run the setup command on this computer to enable Tailscale HTTPS.** appears, complete the **Copy command**, Terminal, and **Check connection** steps above. ### Connection and agent access **A link expired or was already used.** Create a new link on the host. **The computer is offline.** Check its power and network connection. For Tailscale, check that both devices are connected to the same tailnet. For a relay, check the relay connection. Reconnect before sending more work. **An action has no confirmed result.** Select **Check action** before sending another request. The app checks whether the host accepted the first action. **A project is missing.** On the computer, change the phone's **Can work in** under **Settings → Remote access → Allowed devices**. The phone cannot widen its own access.