--- title: "Run Codync on a remote server" description: "Run the Codync host on an always-on exe.dev VM and message Claude Code, Codex and Pi as bots from your iPhone, desktop or terminal. No API keys." url: https://exe-staging.dev/deploy/codync category: "AI agents" updated: 2026-11-02 --- # Run Codync on a remote server Your coding agents as bots you message, on a VM that never sleeps. - **Software:** Codync (https://www.codync.dev) - **Source:** https://github.com/leepokai/Codync - **License:** Apache-2.0 - **Time:** 10 minutes - **Example VM name:** `my-codync` (yours will differ; on the VM, `hostname` prints it) - **Machine-readable:** https://exe-staging.dev/deploy/codync/manifest.json ## What you get - codync-host running as a systemd user service on the VM, back after a reboot - Claude Code, Codex and Pi using exe.dev's LLM integration, with no API key to paste - Codync's lead bot on Claude Code, answering `OK` to `codync-host send` - The host connected to Codync's relay, ready to pair with a phone - A Git project at `~/project` for bots to work in Running on the VM: - **codync-host**: Codync's Rust host, a systemd user service; drives the agents over ACP, port 19222, data in `~/.codync` - **Node.js 24**: Codync's own copy, for the Claude Code, Codex and Pi adapters, data in `~/.codync/node` - **Claude Code, Codex and Pi**: preinstalled; connected to exe.dev's LLM integration, data in `~/.claude, ~/.codex, ~/.pi` - **Your project**, data in `~/project` How it is reached: - ssh my-codync.exe.xyz (private): the terminal UI, pairing, and the desktop app's SSH tunnel - Codync's iPhone app (private): through Codync's end-to-end encrypted relay, after you pair it and sign in to Codync ## Deploy with Shelley Open https://exe-staging.dev/new?prompt=Set%20up%20Codync%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fcodync.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-codync.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-codync.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20codync-host%20running%20as%20a%20systemd%20user%20service%20on%20the%20VM%2C%20back%20after%20a%20reboot%0A-%20Claude%20Code%2C%20Codex%20and%20Pi%20using%20exe.dev%27s%20LLM%20integration%2C%20with%20no%20API%20key%20to%20paste%0A-%20Codync%27s%20lead%20bot%20on%20Claude%20Code%2C%20answering%20%60OK%60%20to%20%60codync-host%20send%60%0A-%20The%20host%20connected%20to%20Codync%27s%20relay%2C%20ready%20to%20pair%20with%20a%20phone%0A-%20A%20Git%20project%20at%20%60~%2Fproject%60%20for%20bots%20to%20work%20in%0A%0ARun%20the%20VM-side%20commands%20in%20%22Set%20up%20the%20VM%22%20only%3B%20skip%20creating%20the%20VM.%0AIf%20%60exeuntu%20configure%60%20reports%20an%20existing%20user%20config%2C%20leave%20it%20alone%2C%0Aand%20leave%20an%20existing%20%60~%2F.pi%2Fagent%2Fexe-dev-llm-integration.json%60%20alone.%0AIf%20%60~%2F.codync%60%20already%20holds%20bots%2C%20ask%20the%20owner%20before%20reinstalling.%0ADon%27t%20run%20%60codync-host%20pair%60%2C%20don%27t%20approve%20access%20requests%2C%20and%20don%27t%0Asign%20in%20to%20any%20Codync%20account%3A%20pairing%20is%20the%20owner%27s%2C%20from%20their%20phone.%0AVerify%20with%20the%20checks%20at%20the%20end%20of%20that%20section%3A%20%60codync-host%20status%60%0Asays%20installed%20and%20running%2C%20%60codync-host%20cloud%60%20says%20%60connected%3A%20true%60%2C%0Aand%20the%20lead%20bot%20answers%20%60OK%60.%20Skip%20the%20later%20sections%20and%20the%20FAQ.%0AFinish%20by%20telling%20the%20owner%20to%20run%20%60ssh%20-t%20%3Cthis%20VM%27s%20name%3E.exe.xyz%0Acodync-host%20tui%60%20to%20meet%20their%20bots%2C%20and%20%60ssh%20-t%20%3Cthis%20VM%27s%0Aname%3E.exe.xyz%20codync-host%20pair%60%20to%20pair%20their%20iPhone%20%28%22Pair%20your%0AiPhone%22%29.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal: ```sh curl -fsSL https://exe-staging.dev/deploy/codync/prompt.txt | ssh exe.dev new --prompt=/dev/stdin ``` Or follow the steps below by hand. [Codync](https://www.codync.dev) turns the coding agents on a computer, Claude Code, Codex, Pi and about 40 more, into named *bots* you message like colleagues: from its iPhone app, its desktop app, or a terminal UI. Each bot has its own agent, folder, approvals and one ongoing chat, and your phone gets a notification when one is done or needs you. It's an open-source take on Grok Bot that brings your own agents. The bots run in `codync-host`, a small Rust service, on the computer where the agents are. Put it on an exe.dev VM and they keep working while your laptop sleeps: the VM is always on, its disk keeps every chat, and your phone reaches it through Codync's encrypted relay with no port to open. Claude Code, Codex and Pi come preinstalled and use exe.dev's [LLM integration](/docs/integrations-llm): no API keys on the VM, and model usage billed to your exe.dev account. > [!NOTE] > Codync ships several releases a day. This page was checked with > codync-host 2.34.2, the release its installer picked on November 2, > 2026; the host updates itself. ## Set up the VM On your computer, create a VM and connect. Pick any free name; if you've already clicked Deploy or have a VM, skip the first command and use its name: ```bash ssh exe.dev new --name=my-codync ssh my-codync.exe.xyz ``` On the VM, connect the agents to the LLM integration. Claude Code and Codex get a setting each; for Pi, the file holds the answer to the question it asks the first time it starts, **Use exe.dev LLM integration**: ```bash exeuntu configure claude exeuntu configure codex mkdir -p ~/.pi/agent [ -e ~/.pi/agent/exe-dev-llm-integration.json ] || echo '{"version": 1, "useExeIntegration": true}' > ~/.pi/agent/exe-dev-llm-integration.json ``` Still on the VM, install the host with Codync's [installer](https://github.com/leepokai/Codync/blob/main/packaging/install.sh), which downloads the release binary into `~/.local/bin` and checks its SHA-256. The link puts it on the `PATH` of one-off SSH commands too. Codync then adds its own Node.js, which the Claude Code, Codex and Pi adapters run on, and saves a copy of the [ACP agent registry](https://agentclientprotocol.com/registry): without one, the first bot Codync makes, your lead bot, can't pick Claude Code and starts on another agent. Last, the service: ```bash curl -fsSL https://raw.githubusercontent.com/leepokai/Codync/main/packaging/install.sh | sh -s -- --host-only sudo ln -sf ~/.local/bin/codync-host /usr/local/bin/codync-host codync-host node curl -fsSL https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json -o ~/.codync/registry.json codync-host install sudo loginctl enable-linger "$USER" git init ~/project ``` Check it. The host takes a few seconds to start; then it's installed and running, it's connected to Codync's relay (`connected: true`, in no account yet), and your lead bot, **Codync**, answers `OK` through Claude Code: ```bash sleep 10 codync-host status codync-host cloud | grep -E '^(connected|account)' codync-host send --bot Codync --wait "Reply with exactly: OK" ``` ## Meet your bots in the terminal The terminal UI needs no account and works from any SSH client, your phone's included. On your computer: ```bash ssh -t my-codync.exe.xyz codync-host tui ```
Codync's terminal UI on the VM: three bots in the roster, and a Claude Code bot describing the VM it runs on
The roster on the left, one chat per bot on the right; each reply hides its tool calls behind "steps".
Press `n` to make a bot and give it a name. It starts on Claude Code in a folder of its own; press `e` for its settings, where **Agent** switches it to Codex or Pi and **Workspace → Choose project folder…** points it at `~/project`. Press `i`, type a task, and `Enter`: > Write index.html in this folder: a one-page site for a very opinionated cat. If the agent wants approval, a card appears: `y` allows it once, `a` always, `n` rejects it. `q` quits the UI; the bots keep going. `?` lists every key. Scripts and other agents can message bots too, and wait for the answer: ```bash ssh my-codync.exe.xyz codync-host send --bot Codync --wait "What's in ~/project?" ``` ## Pair your iPhone Install [Codync from the App Store](https://apps.apple.com/app/codync/id6760984418) (iOS 26 or later) and sign in with Apple, Google or GitHub. On your computer, show a pairing code; it lasts 10 minutes: ```bash ssh -t my-codync.exe.xyz codync-host pair ``` On the phone, scan the QR code, or type the short code printed under it. The VM isn't in an account yet, so the terminal asks whether to let the phone in, and both show a 6-digit code: if they match, answer `y` within 90 seconds. The VM joins your Codync account and its bots appear on the phone, listed under **my-codync**. The phone reaches the VM through Codync's relay, which passes only encrypted traffic; nothing on the VM is opened to the internet. Lock the phone mid-task, and a notification says when the bot is done or wants approval. To add a second phone later, sign in with the same account, tap **Ask for access** under **Manage computers**, and approve it on the VM: ```bash ssh my-codync.exe.xyz codync-host access ssh my-codync.exe.xyz codync-host access approve 123456 ``` Use the 6-digit code the phone shows; `codync-host devices` lists the devices that can use the VM, and `codync-host devices revoke ` removes one. ## Add it to the desktop app Codync's desktop app for macOS, Windows and Linux runs the VM's bots next to your computer's, over SSH with your exe.dev key. It also asks you to sign in to Codync. Run `ssh my-codync.exe.xyz` once in a terminal first, so the VM's host key is saved, then open **Settings → Computers**, choose **Add SSH computer** under **Over SSH**, enter `my-codync.exe.xyz`, and **Trust and connect**. The host is already installed, so there's nothing to install. **Add to account** on its card puts the VM in your Codync account if you haven't paired a phone yet. ## What keeps running - **Laptop closed, phone locked, app quit:** the bots keep working on the VM. Messages you send from the iPhone while the VM can't be reached wait, encrypted, at the relay for up to a day. - **The VM restarts:** systemd starts the host again and it reconnects to the relay. Chats and bots are on disk; each bot resumes its agent's session on its next message. - **Updates:** the host checks for a new release once a day and installs it while no bot is working. Releases wait until the iPhone app that goes with them is in the App Store. ## Make yourself at home - **Bring your code:** [connect a GitHub repo](/docs/integrations-github) and clone it with `git clone https://github.int.exe.xyz//.git`, then make it a bot's workspace. The VM pushes and pulls without a token or SSH key on it. - **Preview what it builds:** ask a bot to serve the app on `0.0.0.0:8000`, then open `https://my-codync.exe.xyz/`. It's private until you [share it](/docs/sharing). - **A direct connection:** put the VM on your Tailscale network with [Tailscale identity federation](/docs/integrations-tailscale-wif), then pair again: the code lists the Tailscale address first, and a phone on your tailnet connects directly instead of through the relay. With Tailscale, `codync-host cloud --disable` takes the VM off the relay entirely; phones that asked for access through your account then can't connect, but those paired with a QR code can. - **Shelley is there too:** exe.dev's own agent, at `https://my-codync.shelley.exe.xyz/`, can hand work to your bots with `codync-host send`. ## Back up and restore Your bots, chats, memory and the VM's Codync identity are in `~/.codync`. For a copy of the whole VM, run this on your computer (choose a free backup name): ```bash ssh exe.dev cp my-codync my-codync-backup ```
Back up just Codync's data On the VM, stop the host for a consistent copy of its database, archive `~/.codync` without the downloads it can fetch again, and start it: ```bash codync-host stop tar -czf ~/codync-$(date +%F).tgz -C ~ --exclude=.codync/node --exclude=.codync/agents .codync systemctl --user start codync-host ``` To restore on a VM set up as above, stop the host, unpack the archive in the home folder, and start it again. `identity.json` in it is the computer's identity: with it, paired phones see the same computer. Run `codync-host node` afterwards if `~/.codync/node` is missing. ```bash codync-host stop tar -xzf ~/codync-2026-11-02.tgz -C ~ systemctl --user start codync-host ```
## Update The host updates itself. To check now, or to turn that off: ```bash codync-host update --check codync-host update --auto off ``` Rerunning the installer updates it too. Update the agents on the VM with `sudo exeuntu update claude`, `sudo exeuntu update codex` and `exeuntu update pi`; the iPhone and desktop apps update from their stores. ## Troubleshooting - **`codync-host: command not found` over SSH.** The link in "Set up the VM" is missing; rerun the `sudo ln -sf` line. - **The lead bot uses OpenCode, or another agent.** The host started before it had the agent registry. Press `e` on the bot in the terminal UI and set **Agent** to **Claude Code**. - **A bot says the agent couldn't start.** On the VM, `claude -p "Reply with exactly: OK"`, `codex exec "Reply with exactly: OK"` and `pi -p "Reply with exactly: OK"` show whether the agents work on their own; rerun `exeuntu configure claude` or `exeuntu configure codex` if not. Pi failing with *Cannot call write after a stream was destroyed* is waiting for its first-run question: create the file from "Set up the VM". - **An agent Codync can't find.** Agents installed after `codync-host install` may be missing from the service's `PATH`; run `codync-host install` again. - **The phone can't pair.** The code expires after 10 minutes and works once: run `codync-host pair` again. A phone turned away with someone else's masked email is signed in to a different Codync account than the one the VM joined (Apple's Hide My Email and Google count as two). `codync-host cloud` shows the VM's account and whether the relay is connected. - **Logs:** `journalctl --user -u codync-host -f`. For everything else, see Codync's [Linux server guide](https://www.codync.dev/docs/linux-servers) and [remote access docs](https://www.codync.dev/docs/remote-access). ## Frequently asked questions ### Do I need a Codync account? Not for the VM or the terminal UI: the host runs, and bots answer, without one. Codync's iPhone and desktop apps ask you to sign in, free, with Apple, Google or GitHub. Pairing then puts the VM in that account. The account alone never unlocks the VM: a new device needs a pairing code or your approval on the VM. ### Do I have to open a port? No. The host connects out to Codync's relay, and the phone reaches it through that, end-to-end encrypted. The terminal UI and the desktop app use SSH. The host listens on port 19222, which exe.dev doesn't expose, and its API answers only callers on the VM itself. exe.dev's [HTTPS proxy](/docs/proxy) isn't involved: the iPhone app can't sign in to exe.dev, so don't point it there. ### Can I use my own Claude or ChatGPT subscription? Yes; Codync runs whatever the agents on the VM are signed in to. For ChatGPT, the simplest way is to connect it as the OpenAI source of your [LLM integration](/docs/integrations-llm): Codex keeps working as set up here. For Claude, run `claude auth login` on the VM after removing `apiKeyHelper` and `env.ANTHROPIC_BASE_URL` from `~/.claude/settings.json` (keep the `statusLine` Codync added), then start a **New session** in each Claude bot. ### How much does it cost? Codync is free and Apache-2.0 licensed, and Codync's relay is free for your own computers and devices. You pay for the VM as part of your exe.dev plan, and model usage through the [LLM integration](/docs/integrations-llm) is billed to your exe.dev account ([models and prices](/llm-gateway-models)). Your lead bot has a **Check in** routine that wakes it at 09:00 and 18:00 UTC, which uses models too; pause it in the bot's details (`R` in the terminal UI, then `space`). ### Which agents can a bot use? Any of the ~40 in the [ACP registry](https://agentclientprotocol.com/registry) that run on Linux. This page sets up Claude Code, Codex and Pi. Others need their own sign-in or key on the VM; OpenCode's free models run out quickly, so [point it at the LLM integration](/deploy/opencode) first. ### Is Android supported? Not publicly yet: Codync's Android app is in closed testing on Google Play. Until then, use the terminal UI from any SSH app on the phone, or the desktop app on macOS, Windows or Linux. ### What doesn't work on a server? Remote screen and the bots' `computer` tool need a desktop session, so they stay off. Connectors and saved API keys need an unlocked keyring (Secret Service), which a headless VM doesn't have, so bots start without connectors. Chat, approvals, group chats, routines, memory and notifications all work. ## Related - [Run Herdr agents on a remote machine](https://exe-staging.dev/deploy/herdr.md): An always-on SSH machine for Herdr, with agents ready and no API keys. - [Run Paseo on a remote server](https://exe-staging.dev/deploy/paseo.md): One app for your coding agents, on a VM you steer from your phone. - [Self-host OpenMausBot, the open-source Grok Bot alternative](https://exe-staging.dev/deploy/openmausbot.md): A team of AI bots, each with a computer that isn't your laptop. - [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop. - [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop. - [Run the Pi coding agent on a remote server](https://exe-staging.dev/deploy/pi.md): An agent that doesn't ask first, on a computer that can take it.