How can we help?
One page for each Waycar feature, from pairing your first Host to fixing a connection.
Get started
- What is Waycar?Waycar is a native iPhone and iPad app for checking on and talking to the coding agents you run in herdr or tmux on your own machines.
- RequirementsWhat your iPhone or iPad and your Host need for Waycar, from iOS 18 to herdr 0.7.5 or tmux 3.2, Node 20, OpenSSH and optional mosh.
- Install Waycar on your HostOne command on your Mac or Linux machine finds herdr or tmux, installs the Waycar host tools, and offers to show a Pairing Code.
- Pair with a Pairing CodeScan or paste the Pairing Code your Host shows to add it to Waycar, with your key made on the device and the host key already pinned.
- Add a Host by handAdd a Host without a Pairing Code by typing its address, port and user, then choosing a Device Key, RSA Key or password to sign in.
- Set up a Mac as a HostTurn on Remote Login, install herdr or tmux and Node 20, then run the Waycar install command to use your Mac as a Waycar Host.
- Set up a Linux HostInstall the OpenSSH server, herdr or tmux 3.2, and Node 20 on your Linux machine, then run the Waycar install command and pair.
- Update Waycar on your HostRun the install command again to update the Waycar plugin and host tools on your Host, add hooks for new agents, and pair another device.
- Remove Waycar from a HostUninstall the Waycar host tools from a Mac or Linux Host, remove its Status Hooks and SSH key, and delete the Host in the app.
The Console
- The ConsoleThe Console lists the agents and shells on all your Hosts in one place, sorted so the ones that need you come first.
- Agent statusWhat Blocked, Done, Working, Idle, and Unknown mean on an agent card, and how status decides the Console's order.
- Filter, search, and pinNarrow the Console with Status pills, the Host and Workspace menus, and search, and pin the agents you want at the top.
- Agent card fieldsChoose which fields each Host's agent cards show in the Console, in up to three rows, from Settings › Agent List Fields.
- Rename, close, and mark agentsClose, rename, move, pin, and mark agents from the Console, one at a time or several at once with Select.
- Closed SessionsWhen an agent exits or its tab closes, Waycar keeps it for 30 days so you can resume the same session with one tap.
- Shells and busy shellsPlain shells show up in the Console as cards like agents, and a busy shell shows Running and the command it's running.
- WorkspacesA Workspace groups the tabs on a Host, like a herdr workspace or a tmux session. Filter, move, and rename them from Waycar.
- AI SummariesAI Summaries add one AI-written sentence to each agent card and notification, saying what the agent is doing or what it needs.
- AI Usage with CodexBarSee how much of your Claude, Codex, and other AI plan limits is left, read by CodexBar on your Host and shown atop the Console.
Start and talk to agents
- Start a new agentUse the New Agent sheet to start a coding agent or a plain shell on any Host, in an existing Workspace or a new folder.
- Start on a new worktreeTurn on New Worktree in New Agent to give an agent a fresh git checkout on its own branch, starting from the latest main.
- Supported agentsThe coding agents Waycar can find and start from New Agent, which ones work in Chat Mode, and how Waycar finds them on a Host.
- The ComposerThe Composer is a local draft box under an agent's terminal where you write a whole message, add files, and send it in one go.
- DictationSpeak a message to an agent instead of typing it. Waycar turns your speech into text on your device, on iOS 26 and later.
- SnippetsSave the phrases you send an agent over and over, then insert one with a tap instead of typing it again.
- Agent SkillsBrowse the Skills and custom commands an agent has on your Host, read one, and insert its command into your message without sending.
- Send photos and filesAttach up to 10 photos or files to a message. Waycar uploads them to your Host and adds their paths so the agent can open them.
- Queued messagesA message you send while your Host is offline waits on your phone as Queued and goes out by itself when the Host is back.
- Chat ModeTalk to Claude Code, Codex, omp, pi or opencode as a simple chat instead of a terminal, with replies in your notifications.
- New Chat from the Home ScreenTouch and hold the Waycar icon and tap New Chat to start a Chat Mode conversation right away, with the keyboard already up.
The terminal
- The live terminalOpen any agent or shell to see its real terminal on your iPhone or iPad, live from your Host, with taps for links, files, and keys.
- Select and copy textTouch and hold text in an agent's terminal to select it in place with draggable handles, then copy it with the system menu.
- Scrolling and jump buttonsDrag to scroll an agent's history, jump to the start or back to live output, and step between the messages you sent.
- The ToolbarThe bar at the bottom of every agent holds your keys, combos, actions, Snippets, and Custom Keys, and you choose and order them in Settings.
- Type straight into the terminalDirect Input sends every key you type straight to the agent's terminal, with a tools keyboard for Esc, Ctrl, arrows, and other keys.
- Files and linksTap a link or file path an agent prints to open it, preview images, PDFs, Markdown, and videos from your Host, and save media to Photos.
- Terminal themes, fonts, and zoomPick a terminal theme for Light Mode and Dark Mode, choose a monospace font, and pinch to zoom the terminal's text size.
- App iconsChoose Waycar's home-screen icon in Settings, from the caboose or the bare prompt mark, each in several colors.
Hosts and connections
- The Hosts sheetSee every Host as a card with its connection, latency, mosh or SSH badge, and live CPU, memory and swap gauges, and manage them.
- A Host's page and checksWhat each section of a Host's page does, how the Preflight checklist reads, and how to pick a herdr session or run the checks again.
- moshWaycar runs agent terminals over mosh so they stay attached when you change networks, and falls back to SSH when mosh can't get through.
- Network changes and reconnectingWhat Waycar does when you switch networks, lose signal, or leave the app, and how your terminal comes back on its own.
- Jump HostReach a machine that isn't on the open internet by connecting through an SSH Jump Host, with host keys checked at both hops.
- Your desk and phone on one terminalWhat happens to your desktop terminal when you open the same agent in Waycar, on herdr and on tmux, and how Take Over Here works on iPad.
- Waycar with tmuxUse Waycar with tmux 3.2 or later: your tmux sessions show up as Workspaces, and you start, open, message and close agents from your phone.
- herdr vs tmuxWaycar works with herdr and with tmux 3.2 or later. Here is what each one supports, side by side, so you can pick or run both.
- Waycar hooks for tmuxSmall Status Hooks in Claude Code, Codex, omp, pi and opencode tell Waycar when a tmux agent is working, blocked or done.
- The waycar command on your HostEvery waycar subcommand on your Host, from pair and status to hooks and notify, plus the herdr plugin actions Waycar adds.
- SSH keys and passwordsChoose how Waycar signs in to a Host over SSH: a Device Key made on your phone, an RSA Key, or a password, and how to add the key on your Host.
- Host keys and fingerprintsHow Waycar checks that it's talking to your real machine, with the host key pinned by the Pairing Code or confirmed on first connect.
Notifications
iPad and CarPlay
- Waycar on iPadUse Waycar on iPad with the agent list in a sidebar beside the open terminal, a hardware keyboard, and drag and drop into the Composer.
- Keyboard shortcutsUse a hardware keyboard on iPad or iPhone to switch agents, search, start a new agent, open Hosts and Settings, and send.
- Multiple windows and Stage ManagerOpen Waycar in more than one iPad window, each on its own agent, and resize freely under Stage Manager.
- CarPlaySee your agents on the car's screen and talk to them out loud with CarPlay, with spoken answers and nothing agent-written on screen.
- Approve commands by voiceIn CarPlay, allow or deny a Claude Code or Codex command approval out loud, and leave risky or long commands for later.
Settings and account
- Settings at a glanceHow to open Waycar's Settings on iPhone and iPad, what each row does, and where to find your version and open-source notices.
- iCloud SyncKeep your Hosts, SSH keys, trusted fingerprints and settings in step across your iPhone and iPad through end-to-end encrypted iCloud Keychain.
- Waycar Pro and LaunchesWaycar is free with 10 Launches in any rolling 30 days; Waycar Pro removes that limit and changes nothing else.
- Privacy and analyticsWhat Waycar keeps on your device, what leaves it, and how to turn usage analytics and AI Summaries on or off.
- SecurityHow Waycar protects your Hosts with on-device SSH keys, pinned host keys, checks at both Jump Host hops, and encrypted notifications.
- AccessibilityHow Waycar works with VoiceOver, Reduce Motion and larger text sizes, including the VoiceOver actions on cards, Hosts, the Toolbar and attachments.
Troubleshooting
- The install command failsWhat each error and warning from the Waycar install command means, and how to fix it so the host tools install on your Host.
- Can't connect to a HostFix a Host that won't connect, matched to the message Waycar shows in the Host's checks, from SSH errors to herdr and tmux setup.
- What connection messages meanWhat each Host connection message in the Console and over an open agent means, from Connecting and Paused to Host Unavailable and Session Ended.
- mosh isn't connectingGet mosh working when a Host shows SSH instead of MOSH or the mosh handshake fails. Install mosh-server and let UDP through.
- Agent status shows UnknownWhy an agent shows Unknown instead of Working, Blocked or Done, and how to fix it with Waycar hooks on tmux or herdr's integrations.
- Chat Mode won't start or sendFix a Chat Mode chat that won't load, won't send, or shows no replies, from an outdated Waycar plugin to opencode setup and trust prompts.
- Notifications don't arriveFix missing Blocked and Done notifications by checking iOS permission, the Host's Notifications switch, the Waycar plugin, and the push relay.
- Live Activities aren't updatingFind out why a Host's Live Activity doesn't appear or stops updating, using the Live Activity line in Waycar's notification settings.
- CarPlay voice isn't workingFix CarPlay voice problems in Waycar, from missing microphone access and speech models to iOS versions older than 26.4.
- Get help and contact supportEmail Waycar support or ask the r/waycar community from Settings, and what to include so we can help quickly.
Didn't find it? Waycar Support covers common problems and how to reach us by email.