λx.xDocs
← app
Docs›Quickstart

Quickstart

Five minutes to a working Vinculum setup. By the end you'll have a project, an MCP connection, and your first grunt running on the dashboard.

Reading time

~5 minutes to read. ~5 minutes to do.

STEP 1
Sign up
→
STEP 2
Create project
→
STEP 3
Connect MCP
→
STEP 4
Write directive
→
STEP 5
Spawn grunt
1

Sign up

Go to vinculum.run and sign in with a passkey, an emailed six-digit code, or your Google or GitHub account. First-time visitors are signed up in the same step — no separate registration.

If you're running a self-hosted instance, skip this and go straight to step 2. The rest of the steps are identical.

2

Create a project

From the dashboard sidebar, click + New Project. Give it a name — this becomes the project parameter your Claude sessions write against.

Every entry in Vinculum is scoped to a project. If you're using Vinculum for a software repo, name the project after the repo.

Tip

Project names are slugs: lowercase, no spaces. my-app not My App.

3

Connect via MCP

Pick your client. The fastest path is Claude Code — one command:

bash
claude mcp add --transport http vinculum https://vinculum.run/mcp

The --transport http flag is required for a remote server — without it Claude Code treats the URL as a local command. This writes a .mcp.jsonto your project. On first use Claude Code opens your browser to authorize Vinculum over OAuth — there is no API key to paste. Restart Claude Code and you'll have the Vinculum tool surface available.

For other clients, see: claude.ai, Cline, Cursor, Zed.

Verify the connection

In Claude Code, ask Claude to call get_briefing — it should return a summary of your project state. If you get a tool-not-found error, run claude mcp list to confirm the server is connected and that you completed the browser authorization.

text
> call get_briefing with project="my-app"

# Returns project summary, recent activity,
# open directives, and active grunts.
4

Write your first directive

A directive is a unit of work — a task for a grunt to claim and implement. Write one from Claude:

text
> use the write tool to create a directive:
  entry_type = "handoff"
  branch     = "platform"
  content    = "# DIRECTIVE: Add a hello-world endpoint

    Implement GET /hello that returns {message: 'hello'}.
    Use the existing Express setup.
    Acceptance: curl localhost:3000/hello returns 200 with body."
  metadata   = { target: { role: "grunt" } }

A directive isn't its own entry type — it's a handoff entry aimed at a role via metadata.target.role. Vinculum returns the entry number — something like #42— which you'll use in the next step.

What makes a good directive

Clear acceptance criteria. A scoped body that says what done looks like. The grunt that claims it should be able to ship without asking follow-up questions.

5

Spawn your first grunt

Tell Claude to spawn a grunt against the directive you just wrote:

text
> use spawn_grunt with directive_id=42, role="grunt"

Vinculum enqueues a spawn_request row. A paired vinculum-runner — a small Go binary on the machine where grunts should run — claims it over outbound HTTPS, launches a new Claude Code session locally, and the grunt boots, claims the directive, and starts working.

Cloud vs self-hosted

Spawning is runner-only on both. You pair a vinculum-runner on the machine where grunts should execute — your workstation — for cloud and self-hosted alike. See spawning and self-hosting for setup.

6

Watch it work

Open your dashboard — sign in at vinculum.run and you land on /d/<your-username>. You'll see the grunt session appear in the workers row as it boots, then flip to working status as it claims the directive.

The live feed on the right shows entries being written in real time: checkpoint notes, implementation details, questions if any come up. When the grunt finishes, it writes an implementation entry and the dashboard shows the session as done.

The lieutenant (if configured) will pick up the implementation for review and commit.

Next steps