Vocion

@vocion/core — the open framework for production AI workflows.

Context as code. Skills as plugins. Review surfaces built in.

Powerful systems should feel simple. The Product Design Manifesto is the bar every feature in this repository is held to: outcomes over activity, accountability with an owner, automation that is earned, complexity hidden without hiding the truth.

New here? Getting started — build an agent workforce from zero walks you from an empty directory to a working workforce, one file type at a time. No code required.

Who this is for

An engineer or tech lead putting a team of agents into production. You have prototyped agents and now need the operating layer: approval gates a person actually sees, an audit trail from an output back to the prompt that produced it, connectors to the systems the work lives in, and a way to change an agent's behavior through a reviewed pull request instead of a text box. Start with docs/getting-started.md, then docs/workspace.md.

A coding agent asked to set Vocion up for a company. Read AGENTS.md first. It carries the verified setup commands, the directory paths for every entity type, how to add an agent, a skill, and an approval gate, how to run lint, type-check, and tests, and an explicit list of what not to touch. Machine-readable index: llms.txt.

When not to use it. If you want a single chatbot, a one-off script, or a hosted no-code builder, Vocion is more machinery than you need. It assumes you run Postgres, you keep configuration in git, and you want a human in the loop on actions that matter. @vocion/core is not published to npm — you install it by cloning this repository and running it yourself.

Versions and release lines

main is Vocion 5.x. The previous major, 4.x, is maintained on the 4.x branch and keeps getting fixes. Every release is a git tag (v5.y.z, v4.y.z) on its line, and an installation pins a release's commit, never a moving branch head.

To stay on 4.x, pin a v4.y.z commit from the 4.x branch, set VOCION_RUNNER_IMAGE to that commit's runner (sha-…, or :4.x), and point any pin-bumping automation at 4.x or latest-4. The exact commands are in docs/deployment/release-lines.md.

What this is

Vocion is a Next.js app + Postgres schema + MCP server + workflow runner. You author your work — Sources, Objects, Skills, Playbooks, Workflows, Missions, Automations, Agents, and Teams — as YAML + markdown in git, apply it to the database, and get a typed runtime with a unified human-review queue, observability, and a plugin ecosystem.

It's built for the part most agent frameworks skip — operating AI in production:

• Three work modes, one runtime — structured Workflows, open-ended Missions (a team of agents plans, works, and produces artifacts under review), and multi-agent Teams.
• Connect the real systems — a built-in connector pack (Google Ads, GA4, HubSpot, Gmail, Slack, Google Drive) on a durable, incremental, client-scoped ingestion pipeline.
• A multi-tenant control plane — tenant Bearer tokens that resolve to a permission principal, a write API (drive the review queue over REST), and MCP over HTTP (the agent/tool plane) — every mutation, token or human, routed through one authorization model.
• Safe by construction — discovery-vs-mutation permissions, an autonomy ladder with approval gates, and cross-client isolation enforced at the query, not the prompt.
• Run the agent loop where you want it — in this app's process, in our own container on AWS Bedrock AgentCore Runtime, or handed over to AWS's managed harness. One setting, harness.runsOn, and the same agent behaves the same way across the first two. Where an agent turn runs explains the three, and which AWS account ends up paying for the tokens.

Layered architecture

This repo is @vocion/core. The full platform is layered:

Layer	npm	Purpose
@vocion/core	this repo	Framework, dashboard, Postgres schema, MCP server, workflow runner
@vocion/sdk	packages/sdk	Stable plugin contract — Skill, PluginManifest, LLM client types
@vocion/plugin-*	packages/plugins/*	Connectors + skills shipped as separate npm packages
vocion-starter	separate repo (planned)	Forkable example install — quick start in 10 minutes

See CONTRIBUTING.md for the layered model, versioning, and compatibility rules.

What you author

Everything you author lives in a workspace — a git-backed directory of YAML + markdown that sits outside this repo, at the peer level of the checkout (../workspace/<org>/). Scaffold one with npm run workspace:scaffold -- <name>; see docs/workspace.md for the authoring guide and docs/entities/ for a field-by-field reference of every file type.

Entity	Path (inside workspace/<org>/)	Shape
Workspace manifest	workspace.yaml	Org id, name, workspace's lead, defaults, dashboard surfaces, base-pack pin
Agent	agents/<slug>.yaml + <slug>.system-prompt.md	LLM orchestrator: prompt, hierarchy, skills, sources, harness settings
Team	teams/<slug>.yaml	Agents grouped under a lead, with an accountable human
Skill	skills/<slug>/SKILL.md	Frontmatter + markdown procedure, read on the model's judgement
Playbook	playbooks/<slug>/SKILL.md	Standing context attached to a skill or an agent by name
Mission	missions/<slug>.yaml	Standing responsibility: goal, success criteria, autonomy level
Worker run	created by the API or by an agent with harness.runsOn: external-worker	A long-running run executed outside the app; Vocion leases, heartbeats, budgets and reaps it (ADR 0004)
Workflow

A base pack ships inside core at packages/core/templates/base/ and layers underneath a workspace: pin it with extends: core@<version>, activate the agents you want with use:, and override any default with a same-slug file marked extends: core.

Apply to DB with npm run workspace:apply -- <path> --project <id|slug>. Every apply records a workspace_version audit row; every tool_call stamps the workspace_sha so any output traces back to the exact prompts that produced it.

Plugin contract

A plugin is an npm package that exports a manifest. Core loads manifests at boot via @vocion/sdk. Typed, distributable, independently versioned.

import type { PluginManifest } from '@vocion/sdk';
import { defineSkill } from '@vocion/sdk';
import { z } from 'zod';

const highlights = defineSkill({
  slug: 'transcript_highlights',
  name: 'Transcript Highlights',
  version: '0.1.0',
  provider: 'openai',
  requiresApproval: false,
  inputSchema: z.object({ transcript: z.string() }),
  outputSchema: z.object({ highlights: z.array(z.object({ quote: z.string() })) }),
  async run(ctx, input) {
    // ... multi-pass LLM, chunking, whatever you need
  },
});

export default {
  id: 'acme.samples',
  version: '0.1.0',
  skills: [highlights],
} satisfies PluginManifest;

The reference plugin lives at packages/plugins/transcript-highlights/; the contract it implements is @vocion/sdk.

Getting started

# 1. Clone + install
git clone <repo-url>
cd vocion-core
npm install

# 2. Configure env
cp packages/core/.env.example packages/core/.env.local
# Edit .env.local — at minimum set DATABASE_URL, AUTH_SECRET, and one LLM provider key.
# AUTH_SECRET signs Auth.js sessions; generate one with `openssl rand -base64 32`.
# There is no third-party auth service to sign up for.
# That provider key is the fallback: a workspace that stores its own is billed on
# its own account instead. See "API credentials" below.

# 3. Start the platform (Postgres + Langfuse)
npm run dev:up

# 4. Apply schema
npm run db:migrate

# 5. Scaffold your workspace — created at ../workspace/<name>, beside this checkout
npm run workspace:scaffold -- {workspace_name}

# 6. Point the app at it and apply it to the DB
export WORKSPACE_PATH=../workspace/{workspace_name}
npm run workspace:apply -- ../workspace/{workspace_name}

# 7. Run dev server
npm run dev:next
# → http://localhost:3000

The workspace is where all tenant context lives — agents, teams, skills, playbooks, missions, workflows, automations, object types, sources. It's a separate git-tracked directory (usually its own repo, or a directory in the deployment repo that carries vocion-core as a submodule), so client context is reviewable in PRs and never mixed into core. Set WORKSPACE_PATH wherever the app runs; without it no workspace is configured. Authoring guide: docs/workspace.md.

Environment topology and deploy patterns: docs/deployment/multiple-environments.md and docs/deployment/parent-project-pattern.md.

MCP server

Author skills + workflows and inspect runs from Claude Code, Cursor, Zed, or any MCP client.

Local (stdio) — single-tenant, for a developer's IDE:

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

Remote (HTTP) — multi-tenant. One endpoint, the org derived from a tenant Bearer token, every tool call scoped to that org under the same permission model as a human:

POST https://your-install/api/mcp
Authorization: Bearer vcn_live_...

ask_workspace sends a message to the workspace: the router picks the agent that handles it, one turn runs with that agent's tools and trust rules, and the reply comes back with the routing decision — see agent tools → Asking the workspace.

Full tool reference + the HTTP transport: reference/mcp.

Control plane (REST + MCP)

For an app or a client integration to drive Vocion — start work, approve, manage scopes — use a tenant Bearer token (vcn_live_…), which resolves into a permission principal. The write API exposes the unified review queue over HTTP (GET /api/v1/reviews, POST /api/v1/reviews/decide); MCP-over-HTTP exposes the agent/tool plane. Both are multi-tenant and Bearer-scoped, and a token mutation is governed exactly like a human action. See the API reference.

API credentials

Credentials travel in both directions, and both live under Dashboard → API credentials.

Inbound — tokens Vocion mints. A vcn_live_… Bearer token is what an outside tool presents to Vocion, as above. Vocion generates the secret, stores only its SHA-256, and shows the plaintext once. A workspace holds as many as it has integrations.

Outbound — keys the workspace supplies. A workspace can paste the key it already holds with a model vendor (OpenAI, Anthropic, Vertex, Azure OpenAI, AWS, or anything else). It is encrypted at rest with AES-256-GCM under a per-org data encryption key, and Vocion uses it when it calls out on that workspace's behalf — so the workspace's own vendor account is billed, not the operator's. One live key per platform per org: saving a second revokes the first.

Which key a call uses. Every outbound vendor call resolves the same way — the workspace's own stored key first, the server's environment variable second. That covers chat models, embeddings on ingest and on query, the rerank pass, the vision tool and image generation. A workspace that has supplied nothing behaves exactly as it did before, on OPENAI_API_KEY / ANTHROPIC_API_KEY. Two internal paths stay on the server's key by design, because no workspace is in scope where they run: discovery detection and the feedback classifier.

Supplied keys never carry a Vocion-side expiry — the vendor that issued the key owns its lifetime. Revoking or replacing is how one ends.

Vendor logins — OAuth apps the workspace supplies. A "Log in with Google" (or Slack, Atlassian, HubSpot, Notion, Zoom, Apollo) runs on the vendor's OAuth app: a client ID and a client secret. It resolves the same way keys do: the workspace's own login app first, the server's env app second (loginClientForNewLogin, env fallback in serverLoginClient). So a workspace admin can save one under Developers → API credentials as a "<Vendor> login app" (credential types in LOGIN_APP_PLATFORMS), and the login button appears on the Connectors page and in chat without a redeploy. The form shows the exact redirect URL to register at the vendor (listPlatformsRoute). A script can do the same with an admin's tenant token: PUT, GET and DELETE on /api/v1/login-apps, which never return the secret.

A refresh token only works with the client that issued it, so each login records the client ID it ran on (loginClientId, stored by the connect callback), and every refresh finds that same app again (loginClientForGrant, called from the shared refresh in loginGrant.ts, Google's and Jira's). Replacing or removing the app makes its logins ask for a new login. GitHub (a GitHub App with a private key and webhook) and PostHog (no secret) stay configured on the server. Per-vendor setup: login apps guide. How the login itself works: connect guide.

Encryption at rest is configured by VOCION_CREDENTIAL_VAULT: local wraps the per-org key with VOCION_CREDENTIAL_VAULT_KEY, which puts the wrapping key and the wrapped key in the same database and is only appropriate for development; kms wraps it with AWS KMS under VOCION_KMS_KEY_ARN, which is what any install holding real customer keys should run. On local, VOCION_CREDENTIAL_VAULT_KEY is mandatory whenever NODE_ENV=production: leaving it unset there makes every credential read and write throw, because the development fallback mints a fresh key per process and every credential saved under the last one becomes permanently unreadable. The app still starts — no code builds a vault at boot — so the failure appears on the first request that touches a credential.

Retrieval

Native first-party. pgvector (HNSW cosine) + Postgres FTS (GIN tsvector) with reciprocal rank fusion across the two arms, optional LLM rerank. No third-party retrieval engine. Embedding and rerank models are environment-level knobs (VOCION_EMBEDDING_MODEL, VOCION_RERANK_MODEL), though the key each one spends comes from the workspace when it has stored one (see API credentials); per-type and per-agent retrieval weighting is authored in the workspace (sourceRelevance on an object type, searchConfig on an agent) — no code change needed.

Tech stack

• Framework: Next.js 16 (App Router), React 19, TypeScript strict
• Database: PostgreSQL 16 + Drizzle ORM
• Auth: Auth.js / NextAuth v5 (next-auth + @auth/drizzle-adapter) — first-party tenancy, sessions carry projectId, RBAC via account/project membership
• LLM: OpenAI, Anthropic — swappable per skill via the provider field
• Retrieval: pgvector + Postgres FTS, RRF hybrid, optional LLM rerank (first-party)
• Observability: Langfuse (LLM traces), OpenTelemetry (spans + metrics)
• Workflows: in-process durable step runner on Postgres
• Chat surfaces: mention an agent in Slack and it replies in the thread; bindings map a channel to an agent, the review queue stays the only place anything is approved (feature flag VOCION_SLACK_EVENTS=1; guide)
• External workers: hours-long runs outside the app — a worker_run control plane with leases, heartbeats, per-run cost and a reaper (feature flag VOCION_EXTERNAL_WORKERS=1; ADR 0004)

Repo layout

packages/
├── core/                        # Next.js app + Postgres schema + MCP + workflow runner
├── sdk/                         # @vocion/sdk — stable plugin contract
└── plugins/
    └── transcript-highlights/   # Reference sample plugin

workspace/<org>/                   # Tenant-owned YAML + markdown (per-tenant workspace repo)
docs/                            # Workspace guide, per-entity reference, object model, deployment

License

@vocion/core is source-available under the Mozilla Public License 2.0 — an OSI-approved open-source license. You can use, self-host, inspect, modify, and build around it, and embed it in a larger proprietary system. MPL is file-level copyleft: when you distribute modified Vocion files, those files stay open under the MPL, but your surrounding application code stays yours.

You own your intelligence. Your data, business context, agent configurations, workflows, evaluation history, and operational outputs remain yours. Vocion is deployable in your environment and portable to another qualified engineering partner — Metacto cannot hold your operating intelligence hostage.

Some uses — white-labeling Vocion itself, distributing it under a proprietary license, a Metacto-supported managed service, proprietary enterprise modules, or commercial warranties/indemnification/SLAs — need a separate agreement. See COMMERCIAL-LICENSE.md.

"Vocion" and the Vocion logos are trademarks of Metacto, Inc.; the MPL does not grant trademark rights.

The logos of the services Vocion connects to (GitHub, HubSpot, Google and the rest) are trademarks of their respective owners. They are shown only to identify the service an integration connects to, and imply no endorsement or partnership. The marks come from simple-icons (CC0-1.0); where a brand is missing there, or its owner's guidelines do not allow this use, Vocion shows the name's initials instead. Each logo's source and licence is listed in packages/core/src/libs/brands/ATTRIBUTION.md.

Docs

• docs/DESIGN-PRINCIPLES.md — the Product Design Manifesto: the principles and the five-question test every product decision must pass
• docs/getting-started.md — start here: zero to a working agent workforce, with an example of every entity type
• AGENTS.md — setup and conventions written for a coding agent working in this repo
• llms.txt — machine-readable index of this repo's public docs
• docs/README.md — docs index
• docs/workspace.md — workspace-as-code: create, author, apply, base packs, commands
• docs/entities/ — one page per authored entity type, field by field
• docs/object-model.md — where every object is authored, stored, executed, and shown
• docs/workspace-pages.md — tenant-defined dashboard pages
• docs/deployment/ — multiple environments, parent-project pattern
• docs/guides/prompt-caching.md — the prompt prefix of every agent turn is cached at the vendor, on by default, nothing to configure; read this for how to turn it off (per agent, per call site, or process-wide with ) and the one case where that is worth doing

Contributing

See CONTRIBUTING.md for commit conventions, local checks, and the contributor licensing terms (MPL 2.0 inbound + DCO sign-off). In short: conventional commits (enforced by commitlint + lefthook), git commit -s to sign off, and run npm run check:types, npm test, npm run lint before committing.