# CouchCode

CouchCode is a local CLI/daemon for controlling AI coding agents from your
phone or other CouchCode clients. It runs on your machine, speaks the
[Agent Client Protocol (ACP)](https://github.com/zed-industries/agent-client-protocol)
to your coding agent, and bridges that session to a paired client — either over
a relay or directly on your local network.

> **Beta.** CouchCode is in beta; commands, configuration, and behavior may
> change between releases.

CouchCode runs on Linux, macOS, and Windows. Local IPC between `couchcode
pair` and the daemon uses one cross-platform transport on every OS: an
authenticated, localhost-only TCP endpoint (127.0.0.1, random port,
high-entropy token in `~/.couchcode/local_ipc.json`).

## Build from source

Requires Rust 1.85 or newer.

```bash
cargo build --release
./target/release/couchcode --version
```

The result is a single static binary at `target/release/couchcode`.

## Usage

```bash
couchcode                   # onboarding wizard (TTY) / help (scripts)
couchcode --help            # top-level help
couchcode start             # background + start-at-login + pairing
couchcode stop              # stop + disable start-at-login
couchcode status [--json]   # human summary (--json for machine output)
couchcode update [--check]  # self-update from the CDN + graceful daemon restart
couchcode run --help        # foreground daemon options
couchcode acp --help        # drive a single ACP agent (standalone)
```

### Relay mode (default)

In relay mode the daemon makes an **outbound-only** connection to the relay and
binds no local network port. The production relay URL
(`wss://relay.couchcode.io/ws/daemon`) is baked in as the default; you can
override it with the `--relay-url` flag, the `COUCHCODE_RELAY_URL` environment
variable, or the `relayUrl` field in `config.json` (flag > env > config >
default). Then pair a client from a second shell.

```bash
couchcode run               # relay mode; uses production URL by default
couchcode pair              # shows a 6-digit code, QR, and deep-link URL
```

### Local mode (same Wi-Fi)

In local mode the daemon binds a LAN WebSocket listener (default `:7780`) and
does not contact any relay.

```bash
couchcode run --local       # add --local-port <N> to override 7780
couchcode pair --local      # pair a client on the same network
```

Agent commands for `start_session` are resolved from the environment:

```bash
COUCHCODE_RS_ACP_AGENTS="agentId=command,agentId2=command2"  # per-agent commands
COUCHCODE_RS_ACP_COMMAND="command"                           # wildcard fallback
```

## Configuration and data

CouchCode stores its data under `~/.couchcode/`:

| Path | Contents |
| --- | --- |
| `~/.couchcode/config.json` | Daemon config (read-only; never written by the daemon). Optional `terminalDetachedTtlMinutes` (default 1440 = 24h): how long a detached terminal's PTY survives before the reaper kills it |
| `~/.couchcode/pairings.json` | Paired-device credentials |
| `~/.couchcode/daemon_identity.json` | Stable routing id for this daemon |
| `~/.couchcode/sessions/` | Persisted sessions |
| `~/.couchcode/preferences.json` | User preferences |

The config path can be overridden with `--config <path>`; the sessions
directory with `COUCHCODE_RS_SESSIONS_DIR`.

## Security and privacy

CouchCode is a local tool that controls coding agents, so it's worth being
explicit about what it does:

- **Runs locally.** The daemon runs on your machine. In relay mode it makes an
  outbound connection only to the relay URL you provide; in local mode it binds
  a LAN listener and contacts no relay.
- **Pairing is the only authorization.** Pairing mints a per-device credential
  stored under `~/.couchcode`. Only a salted SHA-256 verifier is written to
  disk, never the plaintext credential. Credentials are never printed by
  `status`.
- **Relays route, they don't read.** When you use a relay, terminal and session
  traffic is routed through it to your paired clients. The relay routes by a
  non-secret `daemon_id` and treats the payload as opaque.
- **It spawns agent commands by design.** Starting a session launches the
  coding-agent command you configured, as a child process.
- **No telemetry.** CouchCode collects no analytics or telemetry.
- **Logs go to stderr** (controlled by `RUST_LOG`); the daemon does not write
  log files.
- **Helper downloads happen only when used.** Optional features (a cloudflared
  tunnel for remote access, agent-catalog refresh) fetch metadata or helper
  binaries over the network only when you invoke them.

## License

Licensed under the [Apache License 2.0](LICENSE).
