> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Dagger (Local)

> Configure VibeKit with local Dagger sandboxes for fast, offline development

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](https://dagger.io).

## Installation

First, install the Dagger CLI on your system:

**macOS:**

```bash theme={"dark"}
brew install dagger/tap/dagger
```

**Linux:**

```bash theme={"dark"}
curl -fsSL https://dl.dagger.io/dagger/install.sh | BIN_DIR=$HOME/.local/bin sh
```

**Windows:**

```bash theme={"dark"}
winget install Dagger.Cli
```

Then install the Dagger provider package:

```bash theme={"dark"}
npm install @vibe-kit/dagger
```

**Verify installation:**

```bash theme={"dark"}
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)

```typescript theme={"dark"}
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:

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

**Setting up GHCR:**

```bash theme={"dark"}
# 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:

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

**Setting up AWS ECR:**

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
# 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:

```typescript theme={"dark"}
// 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

1. **Check local cache** - Look for existing Docker images locally
2. **Pull from registry** - Attempt to pull pre-built images from configured registry
3. **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:

```typescript theme={"dark"}
// 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:**

```bash theme={"dark"}
# Check Docker status
docker ps

# Start Docker (macOS)
open -a Docker

# Start Docker (Linux)
sudo systemctl start docker
```

**Dagger CLI not found:**

```bash theme={"dark"}
# Reinstall Dagger
curl -fsSL https://dl.dagger.io/install.sh | bash
dagger version
```

**Registry authentication issues:**

```bash theme={"dark"}
# 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):**

```bash theme={"dark"}
# Add user to docker group
sudo usermod -aG docker $USER
# Then log out and back in
```

**Registry image not found:**

```bash theme={"dark"}
# Rebuild and push images
vibekit prebuild --agents claude,codex --push
```