How to run, connect, and operate Collective

Run Collective locally

Install dependencies, seed the demo memory graph, and start the local daemon before connecting an agent.

pnpm install
cargo run -p collective-cli -- demo seed
cargo run -p collective-cli -- daemon

Connect an agent

Agents can use the CLI fallback, MCP stdio tools, or the local HTTP API on port 8787.

cargo run -p collective-cli -- ask "Fix enterprise users being logged out randomly"
cargo run -p collective-mcp

Write source-backed memory

Every memory must include a source reference so future agents can trust and reuse it.

cargo run -p collective-cli -- write "Fixed enterprise logout bug by updating middleware TTL logic."

Production on Vercel

Deploy the Next.js dashboard and native Go API Function together. The dashboard probes the daemon first, then the Vercel API fallback.

pnpm dlx vercel@latest pull --yes --environment=production
pnpm dlx vercel@latest build --prod
pnpm dlx vercel@latest deploy --prod

Clerk

Clerk protects `/app` and `/api` routes in production. Configure ` NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, `CLERK_SECRET_KEY`, `/sign-in`, and `/sign-up` redirect variables in Vercel. Without those keys, local fallback mode remains open for demo work.

API examples

curl -sS https://collective-self.vercel.app/health

curl -sS -X POST https://collective-self.vercel.app/v1/context/query -H 'content-type: application/json' -d '{"orgId":"org_demo","repoId":"repo_demo_saas","agent":"codex","task":"Fix enterprise users being logged out randomly","mode":"debug"}'

curl -sS https://collective-self.vercel.app/v1/orgs/org_demo/graph

Production checklist

• Set Clerk production keys in Vercel.
• Run `pnpm lint`, `pnpm typecheck`, `pnpm test`, `go test ./...`, and `pnpm build`.
• Smoke-test `/health`, `/v1/context/query`, `/docs`, `/support`, and `/sign-in`.
• Verify API keys are scoped and raw secrets are never logged.