Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
Setup and local development
Operational detail moved out of the rule docs. api.md, agent.md and
environment.md are what agents read before changing code; this is what a person
reads once.
First run
cp .env.example .env # fill DATABASE_URL, BETTER_AUTH_SECRET, ALLOWED_SIGN_IN
docker compose up -d # Postgres, matching .env.example
bun run db:migrate && bun run db:seed
bun run dev # app :3000, api :3001, agent :2000
Prisma from the repo root: db:generate, db:migrate, db:push, db:reset,
db:seed, db:studio, db:deploy.
dev depends on ^dev:prepare, so every start applies pending migrations and
regenerates the Prisma client before a single server boots. That is why the first
run needs db:migrate only for the seed that follows it. When the database and
schema.prisma have diverged past what migrate deploy can reconcile,
dev:prepare stops the whole run rather than starting servers against a schema
they do not match — reconcile with db:migrate, or db:reset when the divergence
is an edited migration that has already been applied.
Google Cloud
- Enable the Gmail API and the Google Calendar API on the project.
- Set the consent screen to User type: Internal if you are on Workspace.
gmail.readonlyis a restricted scope, so an External app needs OAuth verification plus an annual CASA assessment. Going External later means the full review — a decision, not a checkbox.
The agent bridge
AGENT_URL="http://127.0.0.1:2000" # 127.0.0.1, not localhost: eve dev is IPv4-only
AGENT_BRIDGE_SECRET="$(openssl rand -base64 32)"
| Agent tab error | Cause |
|---|---|
503 |
AGENT_BRIDGE_SECRET unset in the app's process |
401 |
The two processes hold different secrets, or passThroughEnv in apps/app/turbo.json / apps/agent/turbo.json is missing the pair (Turbo is strict-env) |
502 |
Agent not running, or AGENT_URL wrong |
localDev() accepts any loopback request, so curl 127.0.0.1 proves nothing about
the bridge — send -H 'Host: agent.example.com'. GET /eve/v1/info is the whole
inventory, including a diagnostics count that finds files eve silently ignored.
Running the agent
The agent package's default dev command is interactive eve dev. The root
Turbo task marks it interactive, so select the agent pane and press Enter before
using the eve TUI. Run turbo run dev:headless --filter=agent when a terminal
cannot render the TUI; that uses eve dev --no-ui, and the Turbo pane is the
record because only interactive development writes .eve/logs/ for eve logs.
Reach for the Turbo task rather than bun run --filter=agent dev:headless: the
package script alone skips dev:prepare, so the agent would start against
unmigrated tables.
hooks/activity.ts is the replacement narration, to stderr (the TUI hides
stdout), printing shape everywhere and argument contents outside production only. It
is not the audit trail — hooks/audit.ts writes AgentEvent regardless.
- A second
bun run devfails the whole turbo run. - An orphaned agent holds the port:
lsof -nP -iTCP:2000 -sTCP:LISTEN.
Nothing is researching, and the queue only grows
eve dev never fires schedules on their cron cadence, and everything visible
still works — the row is written, the sheet says Queued, and dispatch.ts is never
called. The poke covers this only when AGENT_BRIDGE_SECRET is set; unset,
poke() returns silently and the queue looks exactly like a slow agent.
Tasks the API did not write (schedule_recheck) and anything queued while the agent
was down still need a manual run:
bun run --filter=agent dispatch # exact production path, both lanes, real credits
Its printed sessionIds are research rows only, so a run that resolved forty logos
prints an empty list and was not idle. eve start and Vercel do run the schedule.
vercel env pull writes .env.local, which wins
.env.local is the override the loader reads last, and vercel env pull writes
production credentials there by default. Pull once and every process silently
points at production — not as an error, but as bun run dev working perfectly against
the live database. On 2026-08-01 eleven migrations landed on Neon from a laptop.
- Pull somewhere inert:
vercel env pull .env.vercel. packages/db/scripts/require-local-db.tsguardsdb:migrate,db:push,db:reset,db:seedand takesALLOW_REMOTE_DB=1.db:deployis unguarded on purpose. It reads the root files directly rather thanprocess.env, because Bun auto-loads the working directory's.envwhile Prisma's CLI only sees@crm/env/load.
Migrations run on the production deploy, and nowhere else
apps/api/scripts/build-func.mjs runs prisma migrate deploy during the crm-api
build, gated on VERCEL_ENV === "production". The schema therefore moves when the
release pull request merges and release deploys — with the code that needs it,
and once rather than once per branch.
Preview deploys share the production database: DATABASE_URL is a single value
across production, preview and development. Until that changes, a preview of a
branch that adds a migration runs against a database without those tables — it
builds, and the pages that touch them fail. Test schema changes locally, where
bun run dev migrates for you. Before the gate existed the reverse was true and
worse: every preview applied its own migrations to the production database, so on
2026-08-07 the live schema ran six migrations ahead of the live code all day.
migrate deploy is not proof the schema is right
The build follows the deploy with prisma migrate diff --exit-code against
schema.prisma and shouts in the build log when they disagree. No pending migrations to apply only means _prisma_migrations has a row for every file —
it says nothing about what the tables actually look like.
They came apart once. A prisma db push shaped production from a laptop, the
migration rows were recorded as applied without their SQL ever running, and
agentConversationAttachment went live without its position column. Every deploy
reported nothing pending, for days, while conversations.builderById returned 500.
The tell is an object in the database that no migration defines — there was an
agentConversationAttachment_submissionId_createdAt_idx that appears in no
migration file, only in a db push of an older schema.
Reconciling is one command, and it is worth reading before running:
DATABASE_URL="…" bunx prisma migrate diff \
--from-config-datasource --to-schema prisma/schema.prisma --script
Secrets hygiene
.gitignore ignores .env and .env.* with one negation for .env.example, so
.env.bak is ignored too. .env.example ships no secret — placeholders are empty
strings, asserted by packages/env/test/root.spec.ts. Generate your own secret;
never reuse one from an example, a tutorial, or another environment.
Tests
bun run --filter=api test
bun run --filter=agent test # integration specs need DATABASE_URL + real Postgres
The test database rebuilds itself when it drifts
bun run db:test creates crm_test and runs migrate deploy on it. The database
name must end in _test; the suite deletes rows it expects to put back, so it
refuses anything else.
migrate deploy only applies migrations that are missing. It never removes a
table, a column or a constraint the database has and the schema does not. A
crm_test built on a branch that was later abandoned therefore keeps that branch's
objects forever, and db:test used to report already exists and move on. The
extra objects are invisible until one of them rejects a write, and then the failure
names a constraint that appears in no migration and in no schema — a stray
trackedEvent_visitorId_fkey once failed seven tracking specs this way, on every
branch, for as long as the database survived.
So db:test now checks the database it found and rebuilds it when either is true:
- It holds a migration this branch does not have. The database came from another branch. The name of the first one is printed.
- It no longer matches
schema.prisma, byprisma migrate diff. Something was pushed or altered by hand.
A rebuild drops the database and re-runs every migration, and it says which of the
two reasons fired. Force one with bun run db:test --reset. Nothing else in the
repo may drop a database, and this may only because the _test suffix is checked
first.
Better Auth 1.7 upgrade
CRM uses Better Auth 1.7.7 and matching plugins.
The account schema stays the same as 1.6.
The existing Slack redirect URL stays valid through slackOAuthCallback.
Microsoft accounts need an identity check before deployment.
Version 1.7 uses the verified Microsoft oid instead of the previous sub account identifier.
Existing Microsoft accounts need a verified mapping from the identity provider before sign-in resumes.
Follow the Microsoft account migration guide.
Do not decode stored tokens without signature verification or infer identifiers from email addresses.
Google account identifiers stay the same.