I

iterate

Monorepo for Iterate's Cloudflare Workers platform. apps/os is the main app — the product dashboard at os.iterate.com.

Environments#

  • The root envs.ts is the typed map of every deployed environment (hostnames, worker names, accounts, resource IDs); Doppler supplies only secrets, one config per env (prd, preview_N; dev/dev_<you> are fully local and never deploy).
  • Each app deploys with its own small scripts: pnpm run deploy --env <name> (build → wrangler deploy with atomic secrets → smoke), ensure-resources, erase-data. Workers are never deleted.
  • Details: DevOps: Cloudflare And Doppler.

Talking to OS#

Run these from apps/os. Plain pnpm cli ... uses your local Doppler setup for apps/os. Wrap in doppler run --config <config> -- ... to target a specific environment; the config supplies URLs and secrets. More on this script pattern: Doppler-backed scripts.

itx API#

OS exposes project capability handles through /api — os' one API. The app CLI authenticates with the config's admin API secret and can run scripts against a project's itx surface:

# your local Doppler setup, normally shared dev
pnpm cli itx --help
 
# production
doppler run --config prd -- pnpm cli itx --help
 
# preview slot 3
doppler run --config preview_3 -- pnpm cli itx --help
 
# local dev server (while pnpm dev is running)
doppler run --config dev -- pnpm cli itx --help

Use pnpm cli itx run --help to run a script against a project.

Claude + project MCP#

Open Claude Code against the OS MCP server for a deployment:

doppler run --config prd -- pnpm cli claude-mcp

The Doppler config picks the environment (prod, preview, or local dev). APP_CONFIG_PROJECT_HOSTNAME_BASES in the config sets the deployed project hostname base (e.g. iterate.app, iterate-preview-3.app); local dev project hosts use <slug>.localhost:<port>. Override with --base-host if needed.

More: apps/os README.

Quick start#

pnpm install
doppler setup --config dev --no-interactive   # once per worktree; doppler.yaml scopes every app dir
pnpm dev                                      # attached local OS dev server (http://localhost:<port>)

Use pnpm dev <action> [flags] for dev server lifecycle controls (status, start --detach, attach, restart, kill). The shared dev config and personal dev_<you> configs are fully local and safe for parallel worktrees; use captun, preview, or production for public callbacks. Details: Dev environments.

Before PRs:

pnpm install && pnpm typecheck && pnpm lint && pnpm knip && pnpm format && pnpm test

How to open a PR (branch hygiene, body shape, screenshots that actually render, previews) — and after open: wait for Iterate Review / review bots, address every CI/review comment (fix or reply + resolve), never leave threads standing, never merge on red CI unless the human explicitly said so: Pull requests.

Repository map#

Start here: apps/os/

Path What
apps/os/ Main app — product dashboard (os.iterate.com; local dev: localhost:<port>)
packages/iterate/ iterate CLI — delegates to local source when run inside this repo
docs/ Detailed documentation
tasks/ Work tracking (markdown + frontmatter)

Other Cloudflare apps (semaphore, …) are supporting services — see docs/architecture.md.

Common commands#

doppler setup --config dev --no-interactive   # once per worktree (or --config dev_<you> for personal secrets)
pnpm dev                      # attached local OS dev server at http://localhost:<port> (see docs/dev-environments.md)
pnpm auth:mint                # mint a session as any user/admin (repo root; dev/preview; wrap in doppler run)
pnpm --dir apps/auth dev      # auth app only (when working on auth itself)
pnpm test && pnpm typecheck && pnpm lint && pnpm format

How do I…? — Dev environments answers: run local dev (fully local, random port, localhost plus project <slug>.localhost hosts), be any user or an admin (minting), point a browser (headless golden path) at local dev or a preview, create a preview environment from your machine, and when you need a public callback URL. Doppler/Cloudflare/deploy details: docs/devops-cloudflare-doppler.md.

Documentation#

Platform & architecture#

Development#

  • Dev environments — local dev, minting identities/admin sessions, browsers for agents, preview-from-local
  • Preview resource GC — how preview slots reclaim their Cloudflare resources: lease-expiry sweep, 3h TTLs, why teardown is decoupled from releasing the slot
  • Remote apps — independently deployed web apps: connect inbound with the born project API key, mount outbound as an itx capability via remoteCapability
  • Coding style
  • Depot CI — workflow editing, Depot CLI commands, monitoring/wait loops, logs, dispatch, metrics, secrets, and gotchas
  • CLI scripts — how to write normal TypeScript scripts and expose them as CLIs
  • TypeScript conventions
  • Design system & React
  • Testing — test lanes, how to run them against any environment, and the retry/timeout policy (one retry layer, fail-fast watchdogs, retry telemetry)
  • Intercepted models — intercepted/* via itx.ai.intercept(handler): deterministic agent/AI testing, the session-bound lifetime + 4901 recovery contract
  • Vitest patterns
  • Domain objects & stream processors
  • Writing & testing stream processors — side-effect guarantees, the obligation pattern, eviction recovery, staleness policy, and the node test harness

Tasks & agent docs#

App-specific#

Was this page helpful?

Powered by Docsbook