Cloud Integration

Overview

VGuard Cloud extends the open-source CLI with a hosted dashboard that gives your team visibility into code quality metrics, convention drift, and AI agent behavior across all your repositories.

What Cloud adds:

• Real-time debt score tracking with 30-day sparklines
• Convention drift detection and timeline
• Rule hit analytics per project and per developer
• SLA monitoring and uptime tracking
• Configurable alerts (Slack, email, webhooks)
• GitHub PR comments and check runs (Team/Enterprise)
• Public dashboard badges for open-source projects

Prerequisites

Before connecting to Cloud, ensure you have:

• VGuard CLI installed: npm install -D @solanticai/vguard
• A project initialized: npx vguard init
• A VGuard Cloud account — sign up here

Step 1: Sign In

Authenticate the CLI with your Cloud account:

npx vguard cloud login

This opens your browser for OAuth authentication. Once approved, a token is stored locally at ~/.vguard/credentials.json. The token persists across sessions.

Step 2: Connect Your Project

Link your local project to a Cloud project:

npx vguard cloud connect

The CLI will:

1. Detect your project name from package.json or the directory name
2. Check if a matching Cloud project exists, or create one
3. Generate an API token for this project
4. Update your vguard.config.ts with the cloud section

Step 3: Regenerate Hooks

After connecting, regenerate your hooks to enable cloud sync:

npx vguard generate

This updates your hook scripts to include the sync step that sends rule hit data to Cloud at the end of each session.

Step 4: Verify

Confirm everything is wired up correctly:

npx vguard doctor

You should see a green checkmark next to "Cloud connection" in the output.

How Data Syncs

When VGuard hooks run during an AI coding session, rule hits are collected locally. At session end (the Stop hook), they are batched and sent to Cloud:

• Endpoint: POST /api/v1/ingest
• Auth: X-API-Key header with your project token
• Format: NDJSON (one JSON object per line)
• Rate limit: 100 requests per minute per project

Each record includes:

Configuration Reference

After running cloud connect, your config file includes a cloud section:

import { defineConfig } from '@solanticai/vguard';

export default defineConfig({
  presets: ['nextjs-15', 'typescript-strict'],
  agents: ['claude-code'],
  cloud: {
    enabled: true,
    projectId: 'your-project-id',
    autoSync: true,
  },
});

Managing API Tokens

You can create and rotate API tokens in the Cloud dashboard:

1. Navigate to Settings > API Tokens
2. Click Create Token and give it a descriptive name
3. Copy the token — it is only shown once
4. Tokens are hashed (SHA-256) server-side and cannot be recovered

To rotate a token:

1. Create a new token
2. Update your local config or re-run npx vguard cloud connect
3. Delete the old token

GitHub Integration

Available on Team and Enterprise plans.

The VGuard GitHub App adds automated PR feedback:

• PR comments: Posts a summary of debt score changes and recent blocks
• Check runs: Creates a pass/fail check based on your quality threshold

To set up:

1. Go to Settings > GitHub in the Cloud dashboard
2. Click Install GitHub App and select your repositories
3. VGuard will automatically detect PRs and post feedback

Disconnecting

To disconnect a project from Cloud:

1. Remove the cloud section from vguard.config.ts
2. Regenerate hooks: npx vguard generate
3. Optionally delete the project in the Cloud dashboard

Local VGuard rules continue to work independently of Cloud.

Troubleshooting

For more help, see the Troubleshooting guide.