Remote access

Open your terminals and Agentty workspaces from another device on your Tailscale network.

Remote access lets you open your Agentty workspaces from a browser on another device — a phone, tablet, or computer — in your own Tailscale network. You can watch terminal sessions, type commands directly, and send prompts to agents, all over the local network inside your Tailscale account.

What you see#

The page is laid out like Agentty itself:

  • Home — where the page opens: how many terminals wait for you and how many are working, the ones waiting with what they ask, the agents at work, every workspace (asleep ones included), and your plugins with their state. Tap a terminal or a workspace to go there. Home at the top of the ☰ menu brings you back.
  • ☰ menu — your groups and workspaces, in the sidebar's order, with their colors, branch and folder. A red number shows how many terminals there wait for your answer. On a wide screen the list stays open on the left.
  • Tabs — the chosen workspace's tabs across the top. A dot shows a tab that is working or waiting for you; ▥2 marks a tab split into two panes.
  • Split panes — when the tab is split, the button at the top right opens the list of its panes, with each one's state and what it asks; tap one to switch to it.
  • The terminal — the chosen pane's live screen in the middle.
  • Chat workspaces — a chat workspace opens as its chat: the conversation, plan usage and a box to write to its lead; Terminal switches to the lead's terminal.
  • Files in the output — a file path in the terminal or the chat (shots/home.png, NOTES.md, src/app.ts) is underlined; tap it to open the file in a viewer over the page, one tab per file. Pictures are shown as they are, Markdown rendered, other text as text; a PDF opens in a tab of its own. Only files in that terminal's project folder open, nothing hidden (.env, .git, …) and no key files.

New tabs — + at the end of the tabs (or beside a workspace on Home) opens a new tab in that workspace with a terminal, Claude Code or Codex, started in the workspace's folder. The page switches to it.

New workspaces — + New workspace (under the workspace list on Home and in the ☰ menu) opens a new workspace in a folder of ~/AgenttyRemote on your Mac, with a terminal, Claude Code or Codex. Browse its folders, make a new one, then pick what to start; the page switches to it. The page can't reach any folder outside ~/AgenttyRemote. Agentty makes that folder the first time, and Show in Finder on the Remote access page opens it on the Mac.

Sleeping workspaces — a workspace that is asleep in Agentty shows Wake up: its saved tabs start again, and the page shows them. Neither changes what your Mac's screen shows.

Plugins — Home lists your installed plugins with their state (running, stopped, stopped with an error) and what each automation is doing right now. The page only shows them: plugin workspaces don't open on the page, and plugins can't be started or stopped from it.

You can type into the terminal directly using an on-screen key bar with Esc, Tab, Shift+Tab, arrow keys, Enter, Ctrl+C, a sticky Ctrl key, and quick buttons (1/2/3) when an agent is asking for an answer. Or send a prompt from the box at the bottom — press Enter on a computer, or Shift+Enter to add a line.

Images — the picture button beside the box attaches photos or screenshots; you can also paste or drop them into the box. They go with your next prompt, as if dropped on the terminal on the Mac, so Claude Code or Codex sees them. Large photos are made smaller on the phone first. The Mac keeps them for a week in Agentty's data folder, readable only by you.

Notify me on the page switches on browser notifications when a session finishes or asks something while you are looking elsewhere.

While you look at a terminal on the page, it takes the page's size: as many columns and lines as fit your screen, so nothing wraps or scrolls sideways. A− and A+ change the text size (kept on that device). When no page shows the terminal any more, it goes back to its size in the app. The page can be added to your home screen as an app.

With Slack, Discord or Telegram notifications set up (Settings → Integrations), each message also carries Open now:

while remote access is on. The address opens the page at that very terminal (after Tailscale and the web password, as always). It is sent only with Include what the agent asks on, since the address names your Mac and your tailnet.

Requirements#

You need:

  • Tailscale installed and connected on your Mac (and on the other device, signed in to the same Tailscale account)
  • MagicDNS and HTTPS certificates enabled for your tailnet (Tailscale admin console → DNS)
  • Tailscale Serve allowed for your tailnet — if not, Agentty shows a button to turn it on

Setup#

  1. Click Remote access (the globe-and-monitor icon) in the side menu
  2. Set a Web password (at least 12 characters in English letters, digits and symbols, entered twice; the eye button shows what you typed)
  3. Press Issue certificate under Before turning it on: Tailscale gets this computer's HTTPS certificate (once per computer; the first time can take a minute, and Tailscale renews it by itself)
  4. Turn on Remote access — the switch works once every step in Before turning it on is checked
  5. Copy the address that appears (https://<machine>.<tailnet>.ts.net:8743/), or tap Open to go there directly
  6. On the other device, sign in with your web password

That's it. Your sessions are now visible on that device.

If Tailscale isn't detected#

The first step of Before turning it on says what is wrong and offers what fixes it. The page checks again by itself, so there's nothing to press once it's put right.

What it saysWhat to do
Not installedGet Tailscale. If you just installed it, open it once.
Switched off on this MacOpen Tailscale and turn on Connect. If macOS asks to add a VPN or allow a system extension, allow it.
Not signed inSign in, with the account you'll also use on your phone.
Waiting for approvalApprove this device on the Machines page, or ask the tailnet's admin.
Background service isn't answeringOpen Tailscale and finish its first-run steps. On a Mac, allow the system extension in System Settings → General → Login Items & Extensions. On Windows, restart the computer. On Linux, run sudo systemctl enable --now tailscaled, then sudo tailscale up.
macOS is waiting for you to allow itIn System Settings → General → Login Items & Extensions → Network Extensions, turn on Tailscale.
Another VPN may be blocking itDisconnect the VPN named there, then turn on Connect in Tailscale.
This Mac account isn't allowedTailscale's access file is for administrator accounts only. Use one, or give this account administrator rights in System Settings → Users & Groups.
Tailscale refused this accountOn Linux, run sudo tailscale set --operator=$USER once. On Windows, another account may be using Tailscale. On a Mac a company manages, a policy may be blocking it.
Can't read Tailscale's answerQuit and reopen Tailscale, or update it. The tool's own message is shown under the text.

Still stuck? Have an agent fix it opens a tab with an agent told what was found: it looks first and asks before changing anything. Copy diagnosis copies the same summary to paste into a question. It holds versions and states, and no account, machine or tailnet name.

Which account? Any Tailscale account works. It doesn't have to match your Apple account or your computer's user account. What has to match is the Tailscale account on this computer and on the device you connect from.

Security#

Remote access is only reachable inside your Tailscale network — never on the public internet. Agentty refuses to run if Funnel is turned on for its port. Getting in takes both of these:

  1. Your Tailscale account — only the account that owns this Mac is let in. Other people who share your tailnet and tagged devices are refused.
  2. The web password — the one you set on the Remote access page.

Someone else's Tailscale account never gets in, even inside your tailnet. Whoever does get past both checks — signed in to your Tailscale account and knowing the web password — can type into your terminals, which means running commands on your Mac. So keep the web password to yourself, don't use it anywhere else, and turn Remote access off when you don't need it.

Only Tailscale can reach Agentty's page at all. Agentty listens where only Tailscale's serve gets in — a private socket where Tailscale can open one, otherwise a local port behind a secret path that only Tailscale is told — so another program or another user account on your Mac can't reach it directly. The page runs only while Tailscale does: when Tailscale disconnects, signs out or quits, Agentty takes the page down within seconds, and brings it back once Tailscale is connected again. While it is on, Agentty also checks every half minute (and when the Mac wakes) that the page still answers through Tailscale; if it doesn't, Agentty restarts remote access by itself, the same as turning it off and on, and the page asks for the web password again.

Failed sign-in attempts are rate-limited: 5 wrong passwords lock the page for 1 minute. Each wrong password after a lock doubles the wait time, up to 1 hour. You get a desktop notification when a device signs in and when the page is locked. If the page is locked and it wasn't you, Unlock on the Remote access page lifts it.

The password is stored only as a hash in your system keychain. Sign-ins last up to 7 days (12 hours idle). Quitting Agentty, changing your password, or tapping Sign out everywhere signs every device out at once.

Keep awake#

While Remote access is on, Agentty keeps your Mac from idle sleep so it stays reachable. The display may still sleep. You can turn this off if you prefer.

A sleeping Mac or a closed laptop cannot be reached.

Remote access stays on across restarts until you turn it off. It uses Tailscale port 8743 and does not interfere with anything else you serve with Tailscale. If something else is already using port 8743, Agentty shows an error instead.

Voice input on the Mac#

You can also talk to your agents right in the app. The microphone shows in agent tabs (Claude Code, Codex, …) and chats — a plain shell has no use for a spoken prompt. The agent CLIs have voice of their own too: Claude Code's /voice dictates into its prompt (hold Space; the audio is transcribed on Anthropic's servers and needs a claude.ai sign-in), and Codex's /voice is a spoken conversation in which Codex answers aloud, not dictation. Agentty's microphone works the same in every agent, in chats and on the remote page, and keeps the audio on your Mac. Click the microphone at the right end of the status bar (or press ⇧⌘M) and speak; the status bar shows Recording 0:05 with a level meter while it listens.

  • ⏎ Enter — stop and send what you said to the terminal straight away, as a prompt.
  • Click the microphone or ⇧⌘M again — stop and only type the words in, to check or fix them before you send.
  • Esc — throw the recording away.

The words go to the terminal that was active when you started. The language is detected from your speech, so Korean, English and mixed prompts all work. The first time, macOS asks for microphone access; if you turned it off, Agentty opens the Microphone page of System Settings for you. Without a model yet, the microphone opens the model setup right there (the same one as below).

Voice prompts#

From the remote page you can speak a prompt instead of typing it. Tap the microphone in the prompt bar, say your prompt, then tap again to stop; the words are transcribed and dropped into the prompt box for you to check and send.

The audio is transcribed on your Mac by a local model — nothing is sent to any outside service. Install a model once from Settings → Voice input (the same card is also on the Remote access page): Large-v3 Turbo (recommended, about 574 MB) or the lighter Small (about 488 MB). It downloads to your Mac, is verified and kept there, and runs on the Mac's GPU. In the same place you can choose the spoken language (Automatic, Korean, English — a short prompt is sometimes mistaken for another language when detected automatically), pick which installed model is used, and delete a model. Once a model is installed, the microphone button appears on the remote page by itself.

Your browser asks for microphone permission the first time, and the page must be served over HTTPS — it is, through Tailscale.

Dev servers#

When a terminal in a workspace runs a local server — npm run dev, rails s, a preview of a static site — its port shows under the workspace's tabs on the page, for example ↗ localhost:3000. Tap it and the server opens in a new browser tab at https://<machine>.<tailnet>.ts.net:3000/, the same address name as the page with the server's port. The first time takes a few seconds while Tailscale sets the port up.

Only you get in, the same as on the page: Agentty answers that address itself and passes a request on to the server only from your Tailscale account and a device signed in with the web password (sign in on the page first). The server sees the request as coming to localhost:<port>, and never gets your Agentty sign-in. It works like the server on the Mac would in a browser there, hot reload included.

The address goes away when the server stops, when remote access is turned off and when Agentty quits. Agentty doesn't open a port that Tailscale already serves for something else, or one shared publicly with Funnel; the page tells you why instead.

Workspaces from the phone apps#

The Agentty Remote apps can send workspaces from the phone. They open under their own name, in a group of their own. Files sent with one are saved in the workspace's folder, under .agentty-remote/, which is kept out of git. In Signed-in devices on the Remote access page, a phone signed in through the app is named Agentty Remote instead of a browser.

From the apps you can also put a workspace to sleep, close a tab (with its splits; it can be reopened from the closed tabs) and move a workspace to the trash. Nothing done from a phone deletes for good: a workspace moved to the trash from a phone keeps its worktree and sync data, and can be restored from the trash like any other.

Chat and orchestrations from the phone apps#

The Agentty Remote apps can show a pane as a chat and follow your orchestrations, with the same sign-in and the same checks as the page. Choosing the chat on the phone doesn't change how the pane shows on the Mac. The Mac stays on the workspace it shows when an orchestration starts or resumes from the phone; a toast says so.

A workspace you left out of remote access, and any orchestration in it, doesn't appear. An orchestration started from the phone works in a folder under ~/AgenttyRemote, and it doesn't read links or files named in its goal beforehand as the Mac's dialog does: the agent just gets the goal.

A conversation holds whatever your agents read and printed. Before it leaves your Mac, your home folder is shortened to ~, and text that looks like a known kind of credential is masked. That catches common shapes, not everything, so treat it like the terminal: it is the same session.

Hiding the feature#

Don't use remote access at all? Turn off Settings → General → Remote access feature (on by default), or press Disable remote access on the Remote access page. Its icon leaves the side menu and remote access turns off. Turn the setting back on to bring it back.

To keep one workspace off the page, open its menu (right-click its card) and choose Hide from remote access. The page no longer lists it or reaches its terminals.

Troubleshooting#

Tailscale is not connected Connect in the Tailscale app on your Mac.

HTTPS certificates are off Enable MagicDNS and HTTPS in your Tailscale admin console (DNS settings). This creates certificates for your tailnet domain.

Couldn't turn on: Tailscale can't reach Agentty's page Often this computer's HTTPS certificate wasn't there yet. Turn remote access off, press Issue certificate, and turn it on again.

Serve is off Agentty shows a button in Settings to turn on Serve. Tap it to open the Tailscale admin console.

This Tailscale account may not use this Agentty (shown on the sign-in page) The other device is signed in to a different Tailscale account. Sign in to the same account as your Mac.

Page says locked (shown instead of the sign-in form) Either you entered the wrong password 5 times, or someone else did. Wait, or check Remote access → Recent activity to see what happened. If it wasn't you, press Unlock on the Remote access page on your Mac.