For AI agents: set up Vocion

If you are an AI coding agent that has been told "set up Vocion in this repo," this page is written for you. Vocion (@vocion/core, MPL-2.0) is a git-authored workspace of agents, teams, skills, and workflows that runs against a Postgres schema and a workflow runner: you do not write application code to add an agent, you add a YAML or Markdown file to a workspace directory and apply it. Setup produces four things: a cloned framework checkout, a scaffolded workspace directory sitting beside it, that workspace's contents loaded into a database with an audited workspace_version row, and a running Next.js app you (or a supervising engineer) can reach at http://localhost:3000. Every step below names the command, what it does, and the exact output you check before moving to the next one — that loop is the part most setup guides skip.

Two things before you start. First, this is @vocion/core: it is not published to npm, so every step clones the repo, never npm install @vocion/core. Second, run every command from the vocion-core checkout root unless noted otherwise.

1. Clone and install

git clone https://github.com/vocion/vocion-core.git
cd vocion-core
npm install

This is an npm workspaces monorepo (package.json → "workspaces": ["packages/core", "packages/sdk", "packages/agent-runtime", "packages/plugins/*"]). npm install resolves all four.

Verify: the command exits 0 and node_modules/ exists at the repo root with no ENOENT errors for any of the four workspace paths above. If it fails on a native module, check the engines.node field in package.json (>=20) against your Node version first.

2. Configure the environment

Copy packages/core/.env.example to packages/core/.env.local and fill in two things: a DATABASE_URL (the example ships postgresql://postgres:postgres@127.0.0.1:5432/vocion as a placeholder — point it at a Postgres instance you control) and one LLM provider key (OPENAI_API_KEY or ANTHROPIC_API_KEY). This is a file edit, not a script — there is no npm command for it, and getting Postgres itself running (local install, container, or a managed instance) is infrastructure outside these scripts, not something vocion-core provides for you.

Verify: packages/core/.env.local exists and DATABASE_URL is non-empty. You cannot verify the database is reachable yet — the next step does that.

3. Apply the database schema

npm run db:migrate

This runs drizzle-kit migrate (packages/core/package.json → "db:migrate": "dotenv -c -- drizzle-kit migrate") against DATABASE_URL, applying every file under packages/core/migrations/.

Verify: the command exits 0. If DATABASE_URL is unreachable it fails immediately with a connection error — fix step 2 before continuing. Re-running is safe; a second run reports no pending migrations.

4. Scaffold a workspace

npm run workspace:scaffold -- my-workspace

This writes a new workspace at ../workspace/my-workspace — one level above the vocion-core checkout — with a workspace.yaml manifest and the primitive directories (agents/, teams/, skills/, missions/, workflows/, automations/, objects/, sources/, and the rest; see docs/workspace.md). scaffold-workspace.ts is filesystem-only — it does not touch the database, so this step has no dependency on step 3 having succeeded.

Verify: ../workspace/my-workspace/workspace.yaml exists, and per docs/workspace.md, "the scaffold is minimal-but-valid — workspace:check passes on it as-is," which the next step confirms.

5. Validate the workspace

export WORKSPACE_PATH=../workspace/my-workspace
npm run workspace:check -- ../workspace/my-workspace

This is apply-workspace.ts --dry-run (packages/core/package.json → "workspace:check": "dotenv -c -- tsx src/scripts/apply-workspace.ts --dry-run"). It parses every YAML and Markdown file and reports what would change.

Verify: the command prints ✓ loaded context from <path>, then org:, sha:, and a count line (agents: N, teams: N, skills: N, ...), then [dry-run] applied to org <id>: followed by one line per resource kind in the form agents created=0 updated=0 unchanged=0 (exact strings from packages/core/src/scripts/apply-workspace.ts, lines 84–99). No errors: block means it passed.

One correction to a common assumption: docs/workspace.md describes this step as making "no DB writes," which is accurate, but it is not DB-free. apply-workspace.ts and packages/core/src/libs/workspace/applier.ts both import the live db client and read current rows to compute the created/updated/unchanged counts even with --dry-run set. Run step 3 before this step, not after — a schema that hasn't been migrated yet will make this fail on a missing table, not skip past it.

6. Apply it

npm run workspace:apply -- ../workspace/my-workspace --project my-workspace

This writes every entity to the database and records a workspace_version audit row stamped with the git SHA of the workspace directory (docs/workspace.md: "records a workspace_version row with the git SHA + diff summary"). Every subsequent tool_call this workspace produces carries that same workspace_sha, so any output traces back to the exact files that produced it.

Verify: same console shape as step 5, but without the [dry-run] prefix, and counts move from created=0 to created=N on a first apply. A non-zero exit code with an errors: block means at least one resource failed — the error lines name the resource and slug.

7. Start the app

npm run dev:next

Verify: the process logs a local URL and http://localhost:3000 returns a page (Next.js 16, App Router). This is a foreground dev server — do not treat a hang as a failure; that's the process staying up.

8. Wire it into the coding agent (optional, but the point of this page)

claude mcp add vocion -- npm --prefix /abs/path/to/vocion-core run mcp:serve

This registers a local, stdio MCP server ("mcp:serve": "dotenv -c -- tsx src/interfaces/mcp/bin.ts", README.md → "MCP server") so the coding agent itself — Claude Code, Cursor, or any MCP client — can read the workspace's agents, skills, and workflows and inspect runs without shelling out to curl.

Verify: in the coding agent's session, list available MCP tools; they should be scoped to the vocion server and resolve against the workspace at WORKSPACE_PATH. A remote, multi-tenant version of the same surface exists at POST /api/mcp behind a vcn_live_… Bearer token, for driving Vocion from a hosted install instead of a local checkout.

What you can skip

• No demo data needed: skip npm run seed:demo — it seeds a demo user, account, and project (packages/core/src/scripts/seed-demo.ts) and is meant for a vocion-demos checkout, not a bare workspace.
• No IDE integration needed yet: skip step 8 and come back to it once the workspace is applied.
• Nothing here needs Docker or Temporal running to reach a working dev loop — those matter once you add scheduled automations or want durable scheduling, not for the setup sequence above.
• What you cannot skip: steps 3, 5, and 6 all need a reachable DATABASE_URL — 3 to create the tables, 5 to read current state for the diff, 6 to write.

What not to touch

Do not add or import a root AGENTS.md or an llms.txt at the vocion-core repo root — as of this writing neither exists on origin/main; do not point the agent at either. Do not run npm install @vocion/core — the package is private and not on npm; the clone in step 1 is the only install path. Do not hand-edit anything under packages/core/migrations/ — that directory is drizzle-kit output, generated by npm run db:generate, not a place to author schema by hand. And once a workspace exists, treat it as the source of truth for that tenant's agents: edit files under ../workspace/<name>/, then re-run workspace:check and workspace:apply — never write agent behavior directly into vocion-core application code.

Related

Once the workspace is applying cleanly, driving Vocion from Claude Code covers the token-registration pattern and the read/write split for a real working session, and the review queue over HTTP covers the /api/v1/reviews surface this setup ultimately gates writes through.

Run the eight steps against a scratch checkout, and open an issue at github.com/vocion/vocion-core if a verification does not match what you actually see.