Reference

Configuration

Conch needs no configuration. These environment variables are for when you want to change where it listens or where it keeps things.

Set them in the environment Conch starts in. Everything else is a setting in the app.

CONCH_PORT=8080 pnpm start

CONCH_HOSTDefault: 127.0.0.1: The address Conch listens on. Anything but this computer also needs CONCH_ALLOW_REMOTE=1, and other devices must sign in.
CONCH_PORTUnset: 4317, or the next free port when another program has it: Pins the port. A pinned port that’s taken is reported, never swapped for the next free one.
CONCH_DOOR_PORTUnset: 4319: The port of the public door, the separate listener on this computer that Teams and WeChat deliver messages to (ADR 0045). It serves only those channels’ signed deliveries; the next free one of the ten after it is used when it’s taken.
CONCH_HTTPS_PORTDefault: 443: Where your own address answers over HTTPS (ADR 0064). Change it only when something in front of Conch sends 443 to another port.
CONCH_HTTP_PORTDefault: 80: Where your own address answers Let’s Encrypt’s check and sends everyone else to HTTPS (ADR 0064). Let’s Encrypt always knocks on port 80, so change it only when something in front of Conch forwards 80 here.
CONCH_ALLOW_REMOTEOne of: 0, 1 · Default: 0: Lets Conch listen beyond this computer. Other devices are refused until sign-in is set up.
CONCH_ALLOWED_HOSTS: Extra hostnames Conch answers to, comma separated: a reverse proxy’s name, say. Your Tailscale name is found by itself.
CONCH_TOKENUnset: no shared key: Legacy: one shared access key, at least 16 characters. Prefer access keys from Settings → Security, which are hashed and can be revoked.
CONCH_HOMEUnset: ~/.conch: Where Conch keeps everything it writes. Use the same value for Conch and for the conch command.
CONCH_ENGINEUnset: every connected provider: Pins one provider and makes it the only one, whatever Settings says: mock for UI work and tests.
CONCH_CLAUDE_PATHUnset: found by itself: The Claude Code program to run, when Conch shouldn’t find it by itself.
CONCH_CODEX_PATHUnset: found by itself: The Codex program to run, when Conch shouldn’t find it by itself.
CONCH_SKILL_SOURCESOne of: auto, off · Unset: auto (off with the mock engine): auto also lists skills from other agents’ folders (~/.agents/skills, ~/.claude/skills, OpenClaw, Hermes); off lists only Conch’s own.
CONCH_SKILL_MARKETOne of: on, off, pretend · Unset: on (pretend with the mock engine): on lets Skills → Discover search Anthropic’s skills on GitHub, ClawHub and skills.sh; off hides Discover; pretend shows a few made-up skills and never goes online (tests).
CONCH_UPDATE_CHECKSOne of: auto, off · Unset: auto (off with the mock engine): auto looks for updates once a day; off only when you press Check now.
CONCH_VAULT_KEYSTOREOne of: auto, file · Unset: auto (file with the mock engine): Where the key that opens Passwords is kept: auto uses this computer’s keychain (macOS Keychain, Windows DPAPI, the Linux Secret Service) when it has one; file a private file beside the vault.
CONCH_WEB_DISTUnset: apps/web/dist: The built web app to serve.
CONCH_OPENOne of: 0, 1 · Default: 0: Opens Conch in your browser once it has started. pnpm start sets it.
CONCH_LOG_LEVELOne of: fatal, error, warn, info, debug, trace, silent · Default: info: How much Conch logs. Logs never hold query strings, headers or bodies.
CONCH_PUBLIC_IPUnset: its own public address, else what the internet sees: This server’s public address, for the DNS record conch setup shows (ADR 0064), when Conch can’t see it itself: behind a NAT it can’t look past.

Where your things live

Everything Conch writes is a plain file in one folder: ~/.conch, or wherever CONCH_HOME points. What's in it lists every file.