Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

17.0 KB
Raw Blame

Codync Dev and production side by side

Codync Dev uses the same source as Codync, with a separate installed identity and local state. Production identifiers and storage locations remain unchanged. Do not copy production credentials, host identity keys, databases or paired devices into Dev; sign in and pair test devices independently.

Both variants use the original Codync icon. The installed name Codync Dev distinguishes the development app.

Desktop development and builds on macOS generate SF Symbols automatically, including the Apple sign-in logo. Packaging rejects a macOS build without the Apple logo assets; a fresh worktree does not need a separate npm run icons step.

Choose a build

Client Production Development
Xcode iPhone scheme iOS iOS Dev
Xcode Screen helper scheme Screen Screen Dev
Desktop packaging npm run dist:<platform>:main npm run dist:<platform>:dev
Foreground host CODYNC_ENV=main cargo run -- serve cargo run -- serve

<platform> is mac, linux, or win. Desktop npm run dev uses the development identity; in a linked worktree it runs a sandbox. In the main checkout, an unpackaged run needs a matching development host binary; it takes the first that exists of CODYNC_HOST_BIN, apps/desktop/build/native/codync-host (left by dist:mac:dev, or rebuilt alone with node tools/native-host.mjs dev) and host/target/debug/codync-host, so after a dist:mac:dev a plain cargo build isn't picked up. On Linux, install a development host as ~/.local/bin/codync-dev-host; the production binary remains codync-host.

Xcode configurations separate environment from optimization: Debug and Release use production; DevDebug and DevRelease use development. The iOS archive remains Release, preserving Xcode Cloud's existing production scheme. Configure schemes through apps/project.yml, then regenerate with xcodegen generate --spec apps/project.yml.

Worktree sandboxes

npm run dev decides by checkout. The main checkout (its .git is a folder) runs the default Codync Dev: the launchd/systemd host on 19223 and ~/.codync-dev, the one a physical iPhone pairs with. A linked worktree (its .git is a file) runs a sandbox beside it, so any number of worktrees and agents test at once:

  • Host data in ~/.codync-dev-<worktree folder>, which also holds the app's session, account and single-instance lock (desktop/). The window and menu bar read Codync Dev (<name>).
  • A port from 19300–19399, picked free on the first run and kept in that folder's sandbox.json, so a paired simulator stays paired.
  • A host built from the worktree's own code (node tools/native-host.mjs dev; on Linux cargo build, honoring CARGO_TARGET_DIR; or CODYNC_HOST_BIN), started and stopped with the app, logging to host.log. No launchd/systemd service, and the dev cloud is off.
  • Nothing in the system's credential store, so a sandbox never prompts and leaves nothing behind when its folder goes. The host runs with CODYNC_VAULT=folder (its key is vault.key beside the data; production builds ignore the switch, and end-to-end test hosts use it too) and the app with Chromium's use-mock-keychain (macOS) and password-store=basic (Linux; Windows keeps its key in the sandbox). Only file permissions protect these, so keep real tokens out of a sandbox and test them on the default Codync Dev. A sandbox made before this switch, or given a copy of a host's database, keeps using that Keychain key while it exists, so a copied database's secrets stay readable; deleting it or --prune leaves any item of its own in Keychain, and nothing cleans it up. On its first start after the switch, its app signs in again (on its own with a test account) and gets a new device key.
  • The run prints the commands that pair a phone or simulator (codync-host pair), create the sandbox's iPhone simulator and open the terminal UI against the sandbox.

Flags go after npm run dev --: --shared takes the default Codync Dev from a worktree (quit the main checkout's first); --sandbox runs a sandbox from the main checkout, for a second session on dev; --name <name> runs the sandbox of that name, for another copy of the same checkout; --cloud lets the sandbox host use the dev cloud (each sandbox then shows as another computer); --cdp opens the DevTools protocol on the sandbox port + 10000; --list shows every sandbox; --prune deletes the ones whose worktree is gone (and their Clerk test accounts and iPhone simulators), so run it after removing worktrees.

A sandbox starts past onboarding (welcome and computer-access setup, only where the window hasn't chosen yet); --onboarding clears those two settings once per start, so the flow comes back (a signed-in sandbox passes the welcome screen by itself and lands on computer-access setup). With CODYNC_CLERK_SECRET_KEY (the Clerk development instance's sk_test_... key) in the git-ignored .env.development at the main checkout's root (copy .env.development.example) (every worktree reads that one file) or the environment, it also signs in its own Clerk test account sandbox-<name>[email protected]: tools/dev-account.mjs finds or creates that user through the Backend API and mints a one-time sign-in token, which account.ts trades for a session (ticket strategy, unpackaged Dev runs only). The token is minted at every start and used only while the sandbox has no active session; the app also requires a pk_test_ publishable key, and the key never reaches the host or the agents. Keys that aren't sk_test_ are refused. Without a key a sandbox starts signed out; it never borrows Codync Dev's login.

Phones follow the same rule. In the main checkout, a simulator's or emulator's Codync Dev keeps your own account. From a worktree, on the worktree's test device (below), npm run phone-account -- --ios <simulator udid> or -- --android <adb serial> (in apps/desktop, beside npm run dev) signs it into the sandbox's test account, so the phone sees the sandbox computer in its account (run the sandbox with --cloud, and answer Add to account when its window asks: a computer joins an account only when told to). It mints a one-time token with the same tools/dev-account.mjs. On iOS the token goes in through the CODYNC_DEV_SIGN_IN_TICKET launch variable (AccountSession.swift). On Android it goes into a file that only adb's run-as can write (NativeAccounts.signInForDevelopment, debug builds only). Both apps trade it only against Clerk's development instance, and only while signed out. In the main checkout the tool needs an explicit --name. It only signs into a sandbox that has run once, so --prune can delete its account; npm run dev prints the exact command.

Test devices for a worktree:

  • iPhone: a new simulator per worktree. npm run dev prints Codync <name>'s udid once it exists, and before that the command that creates it (xcrun simctl create "Codync <name>" "iPhone 17"): run it once, since simctl allows two simulators of one name. Install the worktree's iOS Dev build on it and test only there. The simulator holds Codync Dev's Keychain (device keys, Clerk session), pairings and notification permission, so a fresh one starts clean, carries nothing into another worktree's test, never touches a simulator signed into your account, and lets agents test at once. Allow notifications again on it when a test needs them. --prune deletes it with the sandbox, so it goes when the worktree does.
  • Android: one emulator on this Mac for now, codync_worktree, shared by every session. Only one emulator runs at a time, main checkout included: never start a second AVD or make a new one, not even when the lock is held or another test is slow. This AVD (Pixel 7, API 36 Google APIs, hw.keyboard=yes for the instrumented suite) stays running between tests, so the next one needn't boot it. Your own Codync Dev stays on codync_api36, which only you start, in place of the shared one (adb emu kill first); while it runs, an agent's Android check waits or is reported as not run. Sessions take turns on the lock folder /private/tmp/claude-$(id -u)/android-emulator.lock: mkdir -p its parent, then mkdir the lock (it fails while another test holds it: wait) and write your worktree's path into owner inside it; rm -r gives it back. A lock whose owner worktree is gone, or older than an hour, is stale: remove it and take it. Holding the lock, check adb devices and start the AVD only if no emulator is listed. Start from clean app data: adb shell pm clear com.pokai.Codync.android.dev, then adb shell pm grant com.pokai.Codync.android.dev android.permission.POST_NOTIFICATIONS.

Still shared: macOS sees every unpackaged run as the same Electron app, so permissions and notifications are shared and a codync-dev:// sign-in callback may reach another copy (test sign-in on the default Codync Dev); Codync Screen and computer use need the packaged Codync Dev.app; a global shortcut (the approval island's) goes to whichever app registered it first.

Local secrets

Secrets for running the project locally live in git-ignored env files at the main checkout's root, one per environment: .env.development for the Clerk and Cloudflare development instances, .env.production for production. .gitignore covers .env and .env.* but not .env.*.example, so each file has a committed template (.env.development.example) listing its variables with placeholders; copy it and fill it in. Linked worktrees read the main checkout's file (through git rev-parse --git-common-dir), so a new worktree needs no setup. Real values never go in a template, a commit or a log.

  • Dev tooling reads .env.development only and never loads .env.production; a variable already in the environment wins over the file.
  • A development key is checked before use (CODYNC_CLERK_SECRET_KEY must be sk_test_...), so a production key put there by mistake is refused.
  • Deployed secrets (the Worker's CLERK_SECRET_KEY and the like) are set with wrangler secret put, and kept in these files only when there is no other copy: the device certificate key (CODYNC_DEVICE_CERT_KEY, the Worker's DEVICE_CERT_KEY; hosts compile in its public half, see cloud/README.md).
  • Variables so far: CODYNC_CLERK_SECRET_KEY (see Worktree sandboxes) and CODYNC_DEVICE_CERT_KEY.

Resource ownership

Resource Production Development
Cloud https://api.codync.dev https://dev-api.codync.dev
iOS bundle com.pokai.Codync.ios com.pokai.Codync.ios.dev
iOS App Group group.com.pokai.Codync group.com.pokai.Codync.dev
iOS Keychain group (team prefix omitted) com.pokai.Codync com.pokai.Codync.dev
Desktop bundle com.pokai.Codync com.pokai.Codync.dev
Android application ID com.pokai.Codync.android com.pokai.Codync.android.dev
Linux package / Windows package cache codync-desktop codync-desktop-dev
Desktop account callback com.pokai.Codync://callback com.pokai.Codync.dev://callback
Pairing and widget links codync:// codync-dev://
Host default port 19222 19223
Host data ~/.codync ~/.codync-dev
macOS host launch agent com.pokai.codync.host com.pokai.codync.dev.host
Linux user service codync-host.service codync-dev-host.service
Windows Run key value CodyncHost CodyncDevHost
Windows supervisor codync-hostw.exe codync-dev-hostw.exe
macOS Screen helper identifier com.pokai.Codync.screen com.pokai.Codync.dev.screen
Host credential key (Keychain / Secret Service service) dev.codync.credentials dev.codync.development.credentials

On macOS, native-host.mjs dev signs the host with the Apple Development certificate when this Mac has it, so Keychain keeps trusting Codync Dev's host across rebuilds. After the first signed build it asks one last time for an existing key: choose Always Allow. Without the certificate the host stays ad hoc signed, and Keychain asks again after each rebuild.

The iPhone extensions inherit the parent environment. Electron Dev stores its browser session, account credentials and SSH profiles under its own Codync Dev user-data directory. SSH host-key storage and orphan-tunnel cleanup are also separate. Dev never installs production updates and does not rewrite the shared Claude Code status line.

Remote SSH lookup in Dev accepts the host bundled in /Applications/Codync Dev.app or ~/.local/bin/codync-dev-host; it does not fall back to Homebrew's production host. The desktop's missing-host instructions therefore ask for a Dev build. iOS has no SSH installer or local host to manage. The terminal pairing screen names Codync Dev when it emits a Dev pairing link.

Stop only the variant being replaced. Avoid pkill codync-host, generic bundle lookups, or commands that stop both variants. macOS Dev's host can be stopped with launchctl bootout gui/$(id -u)/com.pokai.codync.dev.host; its app is Codync Dev. Keep each worktree's Apple build products under its own build/dd.

Accounts, callbacks and notifications

Register the development app identifiers, App Group and Sign in with Apple capability with the signing team. Configure the Clerk development instance to accept the new iOS identifier and desktop callback. These settings are external to the repository; a successful simulator build does not prove signing or sign-in works on a device.

Since 2026-10-10 the Clerk development instance lists 7FUM8A8H72.com.pokai.Codync.ios.dev and 7FUM8A8H72.com.pokai.Codync.dev under Native applications, with their ://callback redirects. Without the iOS entry, Clerk rejects the Dev app's native Apple token: the log shows sign_up.failed with "You are not authorized to perform this request", and the app shows only "Couldn't sign in". Check the instance's Logs page first when sign-in fails.

The cloud adds /v1/oauth/callback/dev for connector sign-in, returning codync-dev://oauth. The existing callback keeps returning codync://oauth. Deploy the added route to the development Worker before testing connector sign-in from a Dev client.

The push relay seals the app bundle identifier into new tickets and selects that APNs topic. Existing tickets and registrations without a bundle identifier retain the production topic. Only the production and Dev iOS identifiers are accepted; alert and Live Activity destinations stay separate. Deploy this additive relay change before testing Dev notifications. APNs sandbox/production is a signing/distribution choice, independent of which Codync cloud is used.

Troubleshooting a running host shown as Offline

Observed on 2026-10-09: a MacBook development host was online in development D1, while a Mac mini production app showed the same computer identity's old production record as Offline. Both hosts reported healthy relay connections. Their cloud environments differed.

Before resetting keys or pairing again:

  1. Run the relevant bundled codync-host cloud on each computer. Compare url, registered, connected and last error.
  2. Read /health on that host's port for environment, computerId, binary path and version.
  3. Confirm the desktop app, its host and the iPhone app participating in the test use the same environment. An identical version number or Apple login does not establish this.
  4. Refresh the account list. Working SSH or local access does not prove the clouds match.

An environment change is not a migration of the production account or host. The fresh Dev instance starts without production bots or permissions.

A local build from before the Dev split (2.11.x and earlier) uses the development cloud even when it is named Codync. Its ~/.codync identity stays claimed in the development account, so Codync Dev phones list it and request access to it. Replace such a build with a release build, then unclaim that identity from the development account. Observed on 2026-10-10: a 2.11.2 local build ran as this Mac's production host.

Local verification (2026-10-09)

  • iOS Dev built, signed and launched on a physical iPhone. The app and both extensions use the Dev App Group; the signed app uses the separate Dev Keychain group and development APNs entitlement.
  • The production iOS Release simulator build succeeded with its existing bundle identifiers, App Group and URL scheme. The Swift package's 55 tests passed.
  • A signed macOS Dev app launched into an independent empty workspace. The existing host on 19222 and Dev host on 19223 ran together with different computer identities. Starting and stopping Dev left the original launch agent, token and Claude Code settings unchanged.
  • Desktop type checking and regression tests passed; Rust tests and Clippy passed. Windows and Linux identities and package configuration were checked in tests, but their installed apps have not been exercised on those operating systems.
  • Live Apple account sign-in, connector callbacks and APNs delivery require the external setup and deployments above. Local build success does not verify those flows.