Dagger (Local)

Dagger provides containerized sandboxes that run locally on your machine using Docker and the Dagger engine. This enables fast, offline development with complete isolation and control. Perfect for local development, testing, and when you need the speed of local execution with the isolation of containers. Learn more about Dagger here.

Installation

First, install the Dagger CLI on your system: macOS:

brew install dagger/tap/dagger

Linux:

curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh

Windows:

winget install Dagger.Cli

Then install the Dagger provider package:

npm install @vibe-kit/dagger

Verify installation:

dagger version
docker --version

Configuration

VibeKit uses a builder pattern with method chaining for type safety and flexibility. Configure your Dagger provider and VibeKit instance: Dagger supports multiple container registries for storing and sharing pre-built agent images. Choose the registry that best fits your infrastructure and security requirements.

Default Configuration (Docker Hub)

import { VibeKit } from "@vibe-kit/sdk";
import { createLocalProvider } from "@vibe-kit/dagger";

const provider = createLocalProvider({
  preferRegistryImages: true,             // Use optimized images when available
  registryName: "dockerhub",              // Defaults to DockerHub
  registryUser: "your-dockerhub-username" // Optional: for pushing/pulling images
});

const vibeKit = new VibeKit()
  .withAgent({
    type: "claude",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-sonnet-4-20250514",
  })
  .withSandbox(provider);

// Generate code
const result = await vibeKit.generateCode({ 
  prompt: "Create a REST API with Express.js", 
  mode: "ask" 
});

// Run development server in background
await vibeKit.executeCommand("npm run dev", { background: true });

// Get local host URL
const host = await vibeKit.getHost(3000);
console.log(`Server running at: ${host}`);

// Clean up
await vibeKit.kill();

Using GitHub Container Registry

GitHub Container Registry provides seamless integration with GitHub workflows:

const provider = createLocalProvider({
  registryName: "ghcr",
  registryUser: "github-username",
  githubToken: process.env.GITHUB_TOKEN, // Required for GHCR
});

Setting up GHCR:

# Set GitHub token (requires packages:write permission)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Login to GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Initialize with GHCR
vibekit init --providers dagger --agents claude,codex \
  --registry ghcr --registry-user github-username

Using AWS ECR

AWS Elastic Container Registry for enterprise AWS deployments:

const provider = createLocalProvider({
  registryName: "ecr",
  registryUser: process.env.AWS_ACCOUNT_ID,
  // AWS CLI must be configured with credentials
});

Setting up AWS ECR:

# Configure AWS credentials
aws configure

# Set environment variables
export AWS_ACCOUNT_ID=123456789012
export AWS_REGION=us-east-1

# Login to ECR
aws ecr get-login-password --region $AWS_REGION | \
  docker login --username AWS --password-stdin \
  $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

# Initialize with ECR
vibekit init --providers dagger --agents claude,codex \
  --registry ecr --registry-user $AWS_ACCOUNT_ID

Quick Setup

Initialize with automatic dependency installation:

# Interactive setup with agent selection
vibekit init --providers dagger --agents claude,codex

# With Docker Hub image optimization (default)
docker login
vibekit init --providers dagger --agents claude,codex --upload-images

# With GitHub Container Registry
vibekit init --providers dagger --agents claude,codex \
  --registry ghcr --registry-user github-username --upload-images

# With AWS ECR
vibekit init --providers dagger --agents claude,codex \
  --registry ecr --registry-user $AWS_ACCOUNT_ID --upload-images

The setup will:

Install Docker and Dagger CLI if needed
Pre-build agent images for faster startup
Optionally upload optimized images to your chosen registry
Configure registry authentication

ENV variables and secrets

Configure your Dagger provider using environment variables:

# GitHub integration (optional)
GITHUB_TOKEN=your_github_token_here

# Agent API keys
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key
GEMINI_API_KEY=your_gemini_key
GROK_API_KEY=your_grok_key

# Registry configuration
VIBEKIT_REGISTRY_NAME=ghcr          # Registry type (dockerhub, ghcr, ecr)
VIBEKIT_REGISTRY_USER=myusername    # Registry username
VIBEKIT_PREFER_REGISTRY=true        # Use registry images when available
VIBEKIT_PUSH_IMAGES=true            # Auto-push built images

# Registry-specific authentication
GITHUB_TOKEN=ghp_xxxx               # For GitHub Container Registry
AWS_ACCOUNT_ID=123456789012         # For AWS ECR
AWS_REGION=us-east-1                # For AWS ECR

# Advanced configuration
VIBEKIT_RETRY_ATTEMPTS=3            # Registry operation retries
VIBEKIT_RETRY_DELAY=1000            # Retry delay in ms
VIBEKIT_CONNECTION_TIMEOUT=30000    # Connection timeout in ms
VIBEKIT_CONFIG_PATH=~/.vibekit      # Config directory path
VIBEKIT_LOG_LEVEL=debug              # Enable debug logging

Reference them in your code:

// Dagger provider configuration
const provider = createLocalProvider({
  preferRegistryImages: true,
  dockerHubUser: "your-username",
  // All other config is auto-loaded from env vars
});

// GitHub configuration at SDK level
const vibeKit = new VibeKit()
  .withSandbox(provider)
  .withGithub({
    token: process.env.GITHUB_TOKEN,
    repository: "owner/repo-name",
  });

Configuration Options

The createLocalProvider function accepts these configuration options:

preferRegistryImages (optional): Use pre-built registry images for faster startup (default: true)
registryUser (optional): Registry username for pulling/pushing custom images (works with any registry)
registryName (optional): Which registry to use - supported values:
- "dockerhub" - Docker Hub (default)
- "ghcr" - GitHub Container Registry
- "ecr" - AWS Elastic Container Registry
dockerHubUser (optional, deprecated): Legacy Docker Hub username - use registryUser instead
privateRegistry (optional): Alternative registry URL for enterprise setups
pushImages (optional): Automatically push built images to registry (default: true)
autoInstall (optional): Automatically install missing dependencies (default: false)
retryAttempts (optional): Number of retry attempts for registry operations (default: 3)
retryDelayMs (optional): Delay between retry attempts in milliseconds (default: 1000)

Unique Features

Local Execution

No internet required - Everything runs on your machine
Zero usage fees - No per-minute or per-execution costs
Offline development - Work without network connectivity

Performance Optimization

Local execution - No network latency for container operations
Multi-registry support - Choose the best registry for your infrastructure:
- Docker Hub - Public registry, easy sharing
- GitHub Container Registry - Integrated with GitHub workflows
- AWS ECR - Enterprise AWS deployments
Automatic image caching - Reuse images across sessions
Registry fallback - Automatically falls back to local builds if registry is unavailable

Registry Architecture

VibeKit’s Dagger provider supports multiple container registries through a flexible factory pattern:

Registry Selection

The registry is selected based on the registryName configuration:

dockerhub (default) - Public Docker Hub registry
ghcr - GitHub Container Registry (requires GitHub token)
ecr - AWS Elastic Container Registry (requires AWS credentials)

Image Resolution Strategy

Check local cache - Look for existing Docker images locally
Pull from registry - Attempt to pull pre-built images from configured registry
Build from Dockerfile - Fall back to building from source if needed

Migration Guide

If you’re upgrading from an older version that only supported Docker Hub:

// Old configuration (still supported)
const provider = createLocalProvider({
  dockerHubUser: "myusername"
});

// New configuration (recommended)
const provider = createLocalProvider({
  registryUser: "myusername",     // Universal field
  registryName: "dockerhub"       // Explicit registry selection
});

The dockerHubUser field is maintained for backward compatibility but registryUser is now the recommended universal field that works with all registries.

System Requirements

Docker - Container runtime (automatically installed during setup)
Dagger CLI - Container orchestration engine (automatically installed during setup)
Node.js 18+ - Runtime environment
8GB RAM recommended - For running multiple containers
Registry-specific requirements:
- GitHub Container Registry: GitHub account with packages:write permission
- AWS ECR: AWS account with ECR permissions and configured AWS CLI

Troubleshooting

Docker not running:

# Check Docker status
docker ps

# Start Docker (macOS)
open -a Docker

# Start Docker (Linux)
sudo systemctl start docker

Dagger CLI not found:

# Reinstall Dagger
curl -fsSL https://dl.dagger.io/install.sh | bash
dagger version

Registry authentication issues:

# Docker Hub
docker logout
docker login

# GitHub Container Registry
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# AWS ECR
aws ecr get-login-password --region $AWS_REGION | \
  docker login --username AWS --password-stdin \
  $AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com

Permission errors (Linux):

# Add user to docker group
sudo usermod -aG docker $USER
# Then log out and back in

Registry image not found:

# Rebuild and push images
vibekit prebuild --agents claude,codex --push

Get Started

Agents

Supported Sandboxes

SDK Reference

Installation

Configuration

Default Configuration (Docker Hub)

Using GitHub Container Registry

Using AWS ECR

Quick Setup

ENV variables and secrets

Configuration Options

Unique Features

Local Execution

Performance Optimization

Registry Architecture

Registry Selection

Image Resolution Strategy

Migration Guide

System Requirements

Troubleshooting

​Installation

​Configuration

​Default Configuration (Docker Hub)

​Using GitHub Container Registry

​Using AWS ECR

​Quick Setup

​ENV variables and secrets

​Configuration Options

​Unique Features

​Local Execution

​Performance Optimization

​Registry Architecture

​Registry Selection

​Image Resolution Strategy

​Migration Guide

​System Requirements

​Troubleshooting

Installation

Configuration

Default Configuration (Docker Hub)

Using GitHub Container Registry

Using AWS ECR

Quick Setup

ENV variables and secrets

Configuration Options

Unique Features

Local Execution

Performance Optimization

Registry Architecture

Registry Selection

Image Resolution Strategy

Migration Guide

System Requirements

Troubleshooting