vibeD

🚧🧪 Experimental and under construction 🧪🚧

Workload orchestrator for GenAI-generated artifacts.

vibeD bridges AI coding tools (Claude, Gemini, ChatGPT) with your own Kubernetes infrastructure. It exposes an MCP server that AI tools call to deploy websites and web apps directly to your cluster — getting AI-generated code to a live URL in seconds, with hardware-grade isolation, and without building a container on the deploy path.

Features

• MCP Server — 18 tools for deploying, updating, listing, rolling back, sharing, and deleting artifacts, plus user/department management
• No build on the deploy path — source is injected into a pre-booted, warm sandbox; template images are built by CI on template changes, never per deploy
• Two lanes, auto-selected — a deterministic classifier inspects file names and routes each upload to the fast lane (workerd V8 isolates or static nginx) or the general lane (Kata + Firecracker microVM for arbitrary Node/Python/Go/any-image code)
• Built on agent-sandbox — reuses kubernetes-sigs/agent-sandbox (Sandbox, SandboxTemplate, SandboxClaim, SandboxWarmPool); vibeD adds one CRD, VibedApp
• Warm pools — pre-booted idle sandboxes per template, so a deploy never waits on a cold boot or an image build
• Caddy routing — vibed-router programs Caddy routes per app; wildcard DNS-01 TLS in production, plain HTTP in dev
• Web dashboard — React UI showing all deployed artifacts with status and URLs
• Multiple storage backends — local filesystem, GitHub, or GitLab for source files; S3/MinIO or in-cluster served blobs for the source tarball store
• Per-user isolation — route different users to separate storage repos
• Authentication — API key or OIDC, with optional TLS
• Helm charts — production-ready deployment including RBAC, the control plane, warm pools, and Prometheus metrics

Quick Start

Prerequisites

• Go 1.23+ (with GOTOOLCHAIN=auto) or Go 1.25+
• A Kubernetes cluster — Kind for local dev (make dev sets it up), or any 1.29+ cluster for production
• Container runtime (Podman or Docker)
• kubectl configured to access your cluster

For production you also need agent-sandbox (v0.4.5+), a Kata RuntimeClass (kata-qemu or kata-fc), a sandbox node pool, and object storage — see the installation guide.

Build

git clone https://github.com/vibed-project/vibeD.git
cd vibed
make build

Run Locally (stdio)

./bin/vibed --config vibed.yaml

Run with HTTP Transport (dashboard + MCP endpoint)

./bin/vibed --config vibed.yaml --transport http
# Dashboard: http://localhost:8080
# MCP endpoint: http://localhost:8080/mcp

Local Cluster (Kind)

# Stands up a Kind cluster, installs agent-sandbox + the testbed,
# builds and loads the vibed/controller/router/static-nginx images,
# and helm-installs vibeD with the dev overlay.
make dev

When it finishes, the dashboard is at http://localhost:8080/ and deployed apps are reachable at http://<id>.localhost/ — no kubectl port-forward needed (Kind's extraPortMappings bridge the host ports). The dev install enables only the static-nginx warm pool; enable others with make enable-python-pool / make enable-node-pool. See Local development for details.

Connect to Claude Desktop

Option A: Stdio (vibeD runs locally)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vibed": {
      "command": "/path/to/vibed",
      "args": ["--config", "/path/to/vibed.yaml"]
    }
  }
}

Option B: HTTP (vibeD runs in-cluster)

With vibeD deployed and reachable at localhost:8080:

{
  "mcpServers": {
    "vibed": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}

Then ask Claude: "Create a simple portfolio website and deploy it using vibeD"

MCP Tools

vibeD exposes 18 MCP tools. The core deploy lifecycle:

Tool	Description
deploy_artifact	Deploy source files as a web artifact
update_artifact	Update an existing artifact with new files
list_artifacts	List all deployed artifacts with status
get_artifact_status	Get detailed status for one artifact
get_artifact_logs	Retrieve pod logs for debugging
list_versions	List the version history of an artifact
rollback_artifact	Roll an artifact back to a previous version
delete_artifact	Stop and remove an artifact

Plus list_deployment_targets, sharing (share_artifact, unshare_artifact, and the share-link tools), and user/department management — see the docs.

How It Works

AI Tool (Claude, Gemini, ChatGPT)
    │
    │  MCP / REST  →  deploy_artifact (gzipped source tarball)
    ▼
┌──────────────┐
│    vibed     │  HTTP server · MCP · dashboard
└──────┬───────┘
       │  1. classify source by file names → (lane, template)
       │  2. store the source blob (s3 in prod, served in dev)
       │  3. create a VibedApp CR
       ▼
┌──────────────────┐
│ vibed-controller │  claims a pre-booted sandbox from the matching warm
└──────┬───────────┘  pool, then POSTs the source URL to its vibed-agent
       │
       ▼  vibed-agent (PID 1 in the sandbox) pulls + extracts + starts the app
┌────────────────────────────┬──────────────────────────────────┐
│  fast lane                 │  general lane                     │
│  workerd V8 isolates       │  Kata + Firecracker microVM       │
│  or static-nginx           │  (Node, Python, Go, any image)    │
└────────────────────────────┴──────────────────────────────────┘
       │
       ▼  per-app Service (follows the pod, so the route never goes stale)
┌──────────────┐
│ vibed-router │  watches VibedApp status, programs Caddy routes
└──────┬───────┘
       ▼
   Caddy reverse proxy  →  https://<id>.<domain>

The deploy path never builds an image. A deterministic classifier reads only file names + package.json keys (well under 50 ms) and picks a (lane, template). The controller claims a warm, pre-booted sandbox, and vibed-agent injects the source into /workspace and starts the process. If everything is warm this completes in seconds.

Fast lane — static sites (HTML/CSS/JS, served by an nginx sandbox) and small trusted-language workers (workerd V8 isolates). Sub-second cold start.

General lane — arbitrary code (Node.js, Python, Go, or any base image) runs in a Kata + Firecracker microVM for hardware-grade isolation. New runtime/dependency combinations are handled by an async template builder that refreshes the warm pool out of band — never on the deploy path.

For the full picture see the architecture docs.

Configuration

vibeD has two layers: the app config (vibed.yaml, rendered into a ConfigMap by the chart) and the Helm values (cluster topology). Key app-config sections:

server:
  transport: "http"            # stdio | http
  httpAddr: ":8080"

auth:
  enabled: false               # enable before exposing the API
  mode: "apikey"               # apikey | oidc

deployment:
  appsNamespace: "vibed-apps"  # where /v1 creates VibedApps + warm pools live
  readyTimeout: "10m"          # how long a deploy waits for Ready before failing

storage:
  backend: "local"             # local | github | gitlab  (source files)
  tarball:
    backend: "served"          # served (DEV only) | s3 (PRODUCTION)

store:
  backend: "sqlite"            # sqlite | configmap

Most fields have an environment override (e.g. VIBED_SERVER_TRANSPORT). Cluster topology — namespaces, the Kata RuntimeClass, NetworkPolicy, controller/router/Caddy, and the warm pools — is set through Helm values. See the Configuration Reference for the full list.

Project Structure

cmd/
  vibed/              HTTP server, MCP, dashboard, classifier
  vibed-controller/   VibedApp reconciler (claims sandboxes, injects source)
  vibed-router/       Programs Caddy routes from VibedApp status
  vibed-agent/        PID 1 inside every sandbox (pulls + starts the app)
  vibed-egress-authz/ Egress authorization for sandboxes
  vibed-workerd-loader/ Loads workers into the fast-lane workerd runtime
internal/
  classifier/         Deterministic lane + template selection
  controller/         Reconcile logic for VibedApp
  router/             Caddy route programming
  deployer/           Kubernetes + sandbox deployers
  orchestrator/       Deploy/update/delete lifecycle coordination
  prebaked/           Pre-baked-dependency fast path
  tarball/ storage/   Source blob + source-file storage backends
  store/              Artifact metadata (sqlite, ConfigMap)
  frontend/           Dashboard (embedded React SPA)
  auth/ metrics/ ...  Auth, Prometheus metrics, GC, quota, tracing
pkg/api/              Shared types
deploy/helm/          Helm charts (control plane + warm pools)
templates/            SandboxTemplate / SandboxWarmPool definitions
docs/                 Docusaurus documentation site
web/                  React dashboard source

Development

make build          # Build the vibed binary
make build-all      # Build frontend + backend
make run-http       # Build and run with HTTP transport
make test           # Run unit tests
make e2e            # Run end-to-end tests
make lint           # Run linter
make web-build      # Build React dashboard
make dev            # Full local setup (Kind + agent-sandbox + build + install)
make teardown       # Delete the Kind cluster

Documentation

Full documentation is available in the docs/ directory (Docusaurus site):

make docs-install   # Install doc dependencies
make docs-dev       # Start docs dev server

License

Apache License 2.0 — see LICENSE.