Run locally

Condensate is currently a developer preview. The source repository is private; this setup guide requires repository access. The public documentation and interactive product demo are available to read without an account.

Condensate is an agent runtime that runs Claude Code, Codex and its own agent. This guide starts the runtime, Dex and the review hub from a local checkout and checks that each one answers.

There are two ways to start Condensate. They use different ports and different state directories.

• Installer path (start here if you are new). Start Condensate on a fresh Mac runs one command, ./scripts/install.sh. It starts the runtime on port 24741, the middleware on 24787 and Dex on 25189, and keeps its state in ~/.local/state/condensate-fresh. For PR review on that installation, follow its hub and PR review section.
• Developer path (this guide). You start each service yourself from a local checkout: the runtime on port 4741, the review hub on 4700 and Dex on 5189, with runtime state in ~/.condensate. Use this path when you change Condensate itself.

The runtime, Dex, the review hub and the docs server bind to 127.0.0.1 by default. The middleware binds every interface unless CONDENSATE_HOST is set, so the commands below set it to 127.0.0.1.

Install dependencies

Use the Bun version named in the packageManager field of the root package.json, which is 1.3.13 at the time of writing. From a checkout of the repository:

cd condensate
bun install --frozen-lockfile

--frozen-lockfile stops the install if it would change bun.lock, so you get exactly the versions the repository records.

Start the runtime

In a terminal at the repository root:

bun run --cwd packages/agents-host start

The runtime keeps its data in ~/.condensate/agents-host. The thread log is a SQLite file named threads.db, and a blobs/ directory holds payloads too large to store inline. Two environment variables change the defaults: CONDENSATE_AGENTS_PORT sets the port (4741), and CONDENSATE_AGENTS_DATA_DIR sets the data directory.

Run one runtime per data directory. Two runtimes writing to the same threads.db would contend for one SQLite file.

Check the connection

curl -fsS http://127.0.0.1:4741/health
curl -fsS 'http://127.0.0.1:4741/threads?limit=5'
curl -fsS http://127.0.0.1:4741/workspaces
curl -fsS http://127.0.0.1:4741/accounts

Each request checks one part of the runtime:

A successful read confirms that the runtime answers. It does not confirm that a model account works. Only a real model turn does that.

Open Dex

In a second terminal at the repository root:

bun run --cwd apps/dex-app dev

Open http://127.0.0.1:5189. Dex serves the page and forwards three path prefixes, so the browser sees one origin: /runtime/ goes to port 4741, /hub/ goes to the review hub on 4700, and /middleware/ goes to the middleware on 4787. To confirm that Dex reaches the runtime:

curl -fsS http://127.0.0.1:5189/runtime/health

Add an account and a workspace

A new model task needs two things configured first.

1. An account for each agent you plan to run. Add accounts through Dex's account setup or the runtime's sign-in routes. Credentials go into the account system, outside the checkout. A Claude login has you paste a code back. A Codex login gives you a short code to enter on a verification page, and the runtime finishes the login on its own. See accounts. Codex also needs the exact codex-cli release the runtime was built for, which is 0.160.0. The runtime runs the binary named by CONDENSATE_CODEX_BIN. If that is unset, it runs the CLI that ships inside the ChatGPT desktop app, at /Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex. The engines list on GET /accounts shows the binary it would run, the version it found, the version it needs and, when they differ, why Codex cannot run. Until they match, a Codex spawn is refused with engine-unavailable. The ChatGPT app updates its CLI on its own, so check this list again after an app update.
2. A workspace. A workspace names the repositories a task works in, the accounts it may use and its policy. The runtime reads ~/.condensate/workspaces.json, or the file named by CONDENSATE_WORKSPACES_FILE, and rereads it when it changes. See workspaces.

Add repository review

The review hub is a separate service. It serves the review API and no page. Its root answers with one line of plain text, and Dex shows reviews by reading the hub's /api routes. bun dist/cli.js hub --help lists its options.

From the repository root:

cd apps/gt-review
bun run build
bun dist/cli.js hub --no-open

Confirm that the hub answers:

curl -fsS http://127.0.0.1:4700/api/health

From another terminal in apps/gt-review, register a checkout. The path must be the absolute path of a git checkout:

bun dist/cli.js register /absolute/path/to/checkout

If the hub is running, it adds the checkout at once. If it is not, the path is saved and the hub serves it at its next start.

The hub reads the workspace registry from the runtime's /workspaces when CONDENSATE_AGENTS_URL is set. Otherwise it reads the registry file directly. Repository review and runtime chat use separate upstreams, so a working chat does not show that the hub is running. Check /api/health directly.

Optional: middleware

The middleware serves MCP tools and hook policy to your agents. Dex's Metrics pane also reads its panels from it. It is not needed to run a task. To start it for local use, run CONDENSATE_HOST=127.0.0.1 CONDENSATE_ALLOW_DEV_PRINCIPAL=1 bun backend/index.ts from apps/middleware. CONDENSATE_HOST keeps it on loopback, since without it the middleware binds every interface. CONDENSATE_PORT changes the port (4787). Without an EXECUTOR_URL or another credential setup, CONDENSATE_ALLOW_DEV_PRINCIPAL=1 is required, or its authenticated routes answer 503. To connect Claude Code or Codex to it, install the Condensate plugin. See connect tools and hooks.

Read these docs locally

bun run docs:dev

Open http://127.0.0.1:5192. The command builds the pages and then serves them, and DOCS_PORT changes the port. The docs server serves static documentation only. It does not connect to your agents or credentials.