VOCION
Get a demo
docs/get-started/quickstart.md

Quickstart: local

About fifteen minutes from a clean clone to a running app with your own workspace.

You need

  • Node 20 or later, npm, and Docker (for Postgres with pgvector and Langfuse)
  • A key for one chat model provider: Anthropic (the default), OpenAI, or Amazon Bedrock through AWS credentials
  • An embeddings provider for knowledge search: OpenAI (default) or Bedrock

1. Clone and install

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

2. Configure

cp packages/core/.env.example packages/core/.env.local

Set at least:

DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/vocion
AUTH_SECRET=...              # openssl rand -base64 32
ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, or AWS credentials + VOCION_LLM_PROVIDER=bedrock
OPENAI_API_KEY=...           # embeddings (or VOCION_EMBEDDING_PROVIDER=bedrock)
VOCION_SCHEDULE_OWNER=1      # this process runs schedules and durable jobs

Sign-in is Auth.js with email and password; there is no external auth service. Without VOCION_SCHEDULE_OWNER=1 on exactly one process, schedules, automations and workflows never run.

3. Start Postgres and Langfuse

npm run dev:up        # docker compose: Postgres 16 + pgvector on :5432, Langfuse on :3200
npm run db:migrate

Prefer no Docker? npm run dev runs an embedded Postgres (PGlite) instead. Don't run both: they share port 5432.

4. Create the first user

Sign-up on the web only accepts invites, so the first admin is created from the shell:

npm run user:create --workspace @vocion/core -- \
  --email you@northwind.example --account "Northwind" --password '<choose one>' --role admin

--account creates the account and its first workspace on an empty database.

5. Scaffold and apply a workspace

npm run workspace:scaffold -- northwind        # creates ../workspace/northwind
export WORKSPACE_PATH=../workspace/northwind
npm run workspace:check -- ../workspace/northwind   # validate, no writes
npm run workspace:apply -- ../workspace/northwind --project northwind

The workspace lives beside the checkout, in its own git repo. See Workspace YAML.

6. Run

npm run dev:next

Open http://localhost:3000 and sign in. You land in Workforce chat. Your personal workspace and assistant are created on sign-in.

Next