Quickstart

Clone the repository

git clone https://github.com/yavio-ai/yavio.git
cd yavio

Generate environment secrets

Run the setup script to create a .env file with random secrets:

./scripts/setup-env.sh

This generates cryptographically random values for NEXTAUTH_SECRET, JWT_SECRET, API_KEY_HASH_SECRET, and ENCRYPTION_KEY.

Start the platform

docker compose up -d

This starts five services:

Wait for all health checks to pass:

docker compose ps

All services should show healthy status within about 30 seconds.

Create your account

Open http://localhost:3000 in your browser and register your first account. The first user automatically becomes the workspace owner.

Create a project and API key

1. Create a workspace and project in the dashboard
2. Navigate to the project settings and generate an API key
3. Copy the key — it starts with yav_

Connect the SDK

Point your MCP server's SDK at your local instance:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { withYavio } from "@yavio/sdk";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

const instrumented = withYavio(server, {
  apiKey: "yav_your_key_here",
  endpoint: "http://localhost:3001/v1/events",
});

Or use a .yaviorc.json config file so your code stays clean:

{
  "apiKey": "yav_your_key_here",
  "endpoint": "http://localhost:3001/v1/events"
}

// withYavio() auto-reads .yaviorc.json — no config needed in code
const instrumented = withYavio(server);

Verify events

Invoke a tool on your MCP server and check the dashboard at http://localhost:3000. Events should appear within a few seconds.