Getting started

Codync has two parts. The host (codync-host) is a small background service on the computer where your coding agents are installed. It runs the agents and keeps every bot's chat. The apps (iPhone, desktop, terminal UI) are windows onto that host. You install Codync on your computer once, pair your phone, and create a bot.

What you need

  • A Mac (Apple silicon or Intel), a Windows PC (x64), or a Linux machine (x86_64 or arm64).
  • At least one coding agent on that computer, such as Claude Code or Codex. You can also install one from Codync later. See Agents.
  • Optional: an iPhone with iOS 26 or later. You can also use only the desktop app or the terminal UI.

Codync is free and open source (Apache-2.0). You pay only your agent's provider, through the plan or key you already use.

1. Install Codync on your computer

macOS

Download codync-macos.dmg and drag Codync to Applications. Or install it with Homebrew:

brew install --cask leepokai/codync/codync

Open Codync. The app includes the host and sets it up as a background service the first time it runs. Codync then lives in the menu bar; Open Codync opens the chat window.

The first time a bot reaches a device on your network, such as a model server, macOS asks to let Codync find devices on your local network. Allow it, or turn it on later in System Settings > Privacy & Security > Local Network.

Windows

Download codync-windows-x64.exe and run it. It installs for your user only, and the host starts each time you sign in to Windows. It asks whether to share usage analytics from this computer (what's shared). The installer isn't code-signed yet, so SmartScreen asks you to confirm once: choose More info, then Run anyway. If the window says The host isn't running, your antivirus may have stopped it: see Windows and antivirus.

Codync shows a tray icon. Left-click it to open the chat window, right-click it for the menu. Remote screen isn't available on Windows yet.

Linux

Run the installer in a terminal:

curl -fsSL https://raw.githubusercontent.com/leepokai/Codync/main/packaging/install.sh | sh
codync-host install

The script installs codync-host and, when you run it in a graphical session, the desktop app (codync, an AppImage with a menu entry). codync-host install runs the host as a systemd user service. Opening the desktop app also does this for you.

You can also install the host with Homebrew (brew install leepokai/codync/codync-host), or download the AppImage, .deb or .tar.gz from GitHub Releases. On Linux the desktop app doesn't include the host, so install the host too. AppImages need FUSE 2 to start (on Ubuntu: sudo apt install libfuse2t64).

The first launch of the desktop app

The app first offers to sign in with Apple, Google or GitHub. Signed in, it asks to add the computer to your account, so your phone can find it there and reach it from anywhere. Without an account, choose Continue without an account: phones then connect only over Wi-Fi or Tailscale. It then offers Computer access, which bots need only to use the screen; choose Set up later to skip it. See Computer use.

Setup also offers an optional GitHub star. If you skip it, the desktop app invites you once more when you've sent your fifth message from that computer. That invitation has two actions: Star on GitHub opens the repository, and Not now dismisses it. You can also dismiss it by clicking outside the card or pressing Escape. Opening the repository or dismissing this invitation ends the invitations on that computer.

Once you've sent messages from a computer on 3 different days, the desktop app invites you to support Codync on Ko-fi the next time you open its window, and again at 30 and 90 days. Support on Ko-fi opens the page and ends the invitations; Not now leaves the next one waiting. It never comes in the same opening as a GitHub star invitation or What's new. The terminal UI shows the same invitation when it starts; Escape closes it. The phone apps don't show it.

The computer menu shows a device icon beside each name, helping you distinguish a laptop, Mac mini, or Linux computer. Connection status appears alongside the name (on a separate secondary line on desktop and Android). Tick or untick computers to choose whose bots the list shows; the menu stays open while you pick, so you can change several at once, and All computers shows every one again.

Press ⌘R on macOS or Ctrl+R on Windows and Linux to refresh your computers. A small spinning “Loading…” indicator appears while Codync reconnects and updates the computer list. Repeated presses wait for the current refresh to finish.

Running only the host

For a computer without the desktop app, such as a headless Mac or a server, install the host on its own:

curl -fsSL https://raw.githubusercontent.com/leepokai/Codync/main/packaging/install.sh | sh -s -- --host-only
# or: brew install leepokai/codync/codync-host
codync-host install
codync-host status

codync-host install runs the host as a background service (launchd on macOS, systemd on Linux). Re-run the installer to upgrade. To chat from that machine's terminal, run codync-host tui. For servers and cloud VMs, see Linux servers.

On a Mac, macOS may deny Local Network access to a host installed without the app, so its bots may not reach devices on your local network. Install the app if they need that access.

2. Install the iPhone app

Get Codync on the App Store. It's free and needs iOS 26 or later. On Android, get Codync on Google Play: also free, for Android 10 or later.

Every iPhone release goes through Apple's App Review first, so the App Store version can trail the computer apps. Your computer waits to install an update that needs a newer phone app until the App Store has the iPhone version and Google Play has the Android version. See Updates.

3. Pair your iPhone

Pairing connects your phone to your computer with a QR code. Signing in is optional, with one limit: without an account on both ends, the phone connects only over Wi-Fi or Tailscale. A computer in an account takes only phones of that account. Apple with Hide My Email on one and Google on the other are two different accounts (more in Remote access).

On the computer, show the pairing code:

  • macOS: click Codync in the menu bar, then Pair iPhone…
  • Windows and Linux: open the tray menu, then Pair iPhone…
  • Any desktop app: Settings → Computers, then the Pair iPhone button on the computer.
  • Terminal: run codync-host pair, or press P in the terminal UI.

On the iPhone, open Codync and sign in with Apple, Google or GitHub, or choose Continue without an account. If your account already has a computer, the first page offers it: tap Pair a new computer to set up another one here, or see below to use that one. Tap Continue, then scan the code. The iPhone Camera app can scan it too. If you can't scan, copy the pairing link on the computer and paste it into the field under the viewfinder. To pair later, tap the account button at the top left of the Bots tab, then Scan a computer's code.

The iPhone app has three tabs: Bots (your bots and chats), State (widgets, Live Activities and usage limits) and Settings (this iPhone's own settings). Each computer's settings, such as Extensions, voice chat and push notifications, are in Manage computers: tap the connection status at the top of the Bots tab (such as 1 connected).

A pairing code expires. If pairing fails, show a new code on the computer and scan again.

After pairing, the phone connects directly when it's on the same Wi-Fi or Tailscale network as the computer. Anywhere else it goes through the Codync relay, end-to-end encrypted, if the computer is in the phone's account and Reach from anywhere is on. A computer in no account stays reachable only directly; a signed-in phone can add it later with Add to account in Manage computers. See Remote access.

If you signed in to the same account on the computer and the phone, the phone can ask the computer for access instead of scanning: the first page lists your account's computers with Ask for access. The computer then shows the request and a code for you to check. See Remote access.

Started on the phone, with Codync not on the computer yet? The install page has Copy website link: open that link on the computer and download Codync there. Sign in there with the same account and choose Add to account, and the computer shows up on the phone the next time you open the app.

4. Meet your lead bot

Your computer already has a bot: your lead bot, Codync, with a star on its avatar. Message it, or call it and it speaks first. See Your lead bot.

You can make more bots, for other folders or agents, whenever you like:

  • iPhone: on the Bots tab, tap +, then New bot.
  • Desktop: click + at the top of the sidebar, then New bot, or press Cmd+N (Ctrl+N on Windows and Linux).
  • Terminal UI: press n.

Pick an avatar and type a name, then create it. The name is optional: a bot without one is called "New Bot" until Codync names it after its first few conversations.

Every bot, your lead bot too, starts with these defaults, which you can change in its settings:

  • Agent: Claude Code when it can run on the computer, otherwise the first agent Codync knows that can.
  • Workspace: Own folder, a folder of its own that Codync keeps versions of (see Working folders and git).
  • Permissions: the agent's Auto mode, so it asks you only about what it won't decide on its own (Ask me when the agent has no Auto mode).
  • Notifications: on.
  • Connectors and skills: every one installed on the computer is turned on (connectors only when the computer's credential store is available; see Linux servers).

Note: New bots let the agent do what's safe and ask you about the rest on an approval card. To review every request, set Permissions to a mode such as Manual; to skip the cards, set it to Approve automatically. See Bots.

If the bot's agent isn't signed in, the chat shows a card saying it needs you to sign in before your first message. Tap Sign in and follow the steps. See Agents.

5. Send it a message

Open the bot and type in the box at the bottom. It says "Ask" followed by the bot's name. Press Return on the desktop, tap the send button on the iPhone, or press Enter in the terminal UI.

While the bot works, a line under the last message shows what it's doing and for how long. Its reply arrives as a complete message. If it asks for approval, an approval card appears in the chat. Every tool call and step is one tap away in Full conversation.

When the bot finishes or needs you, your iPhone gets a notification, unless the Codync app is open on it. See Conversations.

Interface language

Choose Language in Settings → General on the desktop or Settings on the iPhone or Android. You can follow your system language or choose English, Simplified Chinese, Traditional Chinese, Japanese, Korean, French, German, Spanish, Português (Brasil), Русский or Italiano. In the terminal UI, open the command palette with Ctrl+K and choose App language… to cycle through the choices.

Each device keeps its own choice. Follow system uses Brazilian Portuguese for Portuguese system languages, including pt and pt-BR; unsupported languages use English. This changes the interface, not your conversations, bot names or commands.

Queue status, routine notices and trace labels follow this choice too. Bot and routine names, custom tool titles and message contents stay as written.

Next steps

  • Bots: set up a bot's agent, folder, approvals and more.
  • Agents: install and sign in to more coding agents.
  • Conversations: files, approvals, replies and notifications.
  • Group chats: put several bots in one room.

Community and help

Ask questions and share feedback on Discord, or join the Telegram group for Codync users in China to exchange tips in Chinese.