Worklet

A powerful tool for running projects in isolated Docker containers with Docker-in-Docker support.

Why Worklet?

• Isolated Environments: Run your project in clean Docker containers
• Docker-in-Docker: Run complex Docker workflows in complete isolation
• Service Discovery: Automatic subdomain routing for multi-service projects
• Zero Configuration: Works out of the box with sensible defaults
• Real-time Development: Mount mode for live code changes

Quick Start

# Install worklet
go install github.com/nolanleung/worklet@latest

# Initialize configuration  
worklet init

# Run your project in an isolated container
worklet run

# Or run with your local directory mounted
worklet run --mount

# Run a specific command
worklet run npm test

# Open interactive session manager
worklet

Installation

From Source

go install github.com/nolanleung/worklet@latest

Manual Build

git clone https://github.com/nolanleung/worklet
cd worklet
go build -o worklet .
sudo mv worklet /usr/local/bin/

Features

🚀 Instant Isolated Environments

Run your project in a clean Docker container with one command. Each session is isolated, allowing you to experiment without fear.

🐳 True Docker-in-Docker Support

• Full isolation mode (default): Runs a separate Docker daemon inside the container
• Shared mode: Uses host Docker daemon for resource efficiency
• Perfect for testing Docker Compose setups, building images, or running containerized tests

🔧 Flexible Run Modes

• Isolated mode (default): Creates a persistent isolated environment
• Mount mode (--mount): Mounts your current directory for real-time development
• Temporary mode (--temp): Creates a temporary environment that auto-cleans up

🌐 Service Discovery & Routing

• Automatic subdomain routing for multi-service projects
• Access services via service.project-name.worklet.sh
• Built-in proxy server for local development

💻 VSCode Integration

• Open containers directly in VSCode with Dev Containers extension
• Automatic devcontainer.json generation with your extensions
• Seamless development experience with full IDE support

🔌 Self-Contained Binary

The worklet binary includes all necessary scripts. No external dependencies beyond Docker.

🚀 Init Scripts & SSH Support

• Run initialization commands automatically when containers start
• Mount SSH credentials for Git operations inside containers
• Support for private repositories and SSH-based workflows

Configuration

Create a .worklet.jsonc file in your repository root:

{
  "name": "my-project",     // Project name for container naming
  "run": {
    "image": "worklet/base:latest",  // Base Docker image (default: worklet/base:latest)
    "privileged": true,              // Run with Docker-in-Docker
    "isolation": "full",             // "full" for DinD, "shared" for socket mount
    "command": ["/bin/sh"],          // Default command (optional)
    "environment": {                 // Environment variables
      "NODE_ENV": "development",
      "DEBUG": "true"
    },
    "volumes": [                     // Additional volume mounts
      "/var/lib/mysql"
    ],
    "initScript": [                  // Commands to run on container start
      "apk add --no-cache nodejs npm python3",
      "npm install -g pnpm",
      "echo 'Welcome to Worklet!'"
    ],
    "credentials": {
      "claude": true,                // Mount Claude credentials if available
      "ssh": true                    // Mount SSH credentials for Git operations
    },
    "composePath": "docker-compose.yml"  // Path to docker-compose file (optional)
  },
  "services": [                      // Services exposed by your project
    {
      "name": "web",
      "port": 3000,
      "subdomain": "app"             // Access via app.my-project.worklet.sh
    },
    {
      "name": "api", 
      "port": 3001,
      "subdomain": "api"             // Access via api.my-project.worklet.sh
    }
  ]
}

Command Reference

worklet

Launch interactive session manager to view and manage all active worklet sessions.

worklet                         # Open interactive CLI
# Features:
# - View all active sessions with project info
# - Connect to sessions (Enter key)
# - Open in VSCode (v key)
# - Delete sessions (d key)
# - Refresh view (r key)

worklet init

Initialize a new .worklet.jsonc configuration file.

worklet init
# Creates .worklet.jsonc with default configuration

worklet run

Run your project in a Docker container.

worklet run                      # Run in isolated environment
worklet run --mount              # Run with current directory mounted
worklet run --temp               # Run in temporary environment
worklet run npm test             # Run specific command
worklet run --mount npm start    # Run with mount and command

# Terminal server options
worklet run --no-terminal        # Disable terminal server
worklet run --open-terminal      # Auto-open terminal in browser
worklet run --terminal-port 8080 # Use custom terminal port

# Credential options
worklet run --link-claude        # Auto-link Claude credentials (default for cloned repos)

worklet terminal

Start a web-based terminal server for browser-based access to containers.

worklet terminal                 # Start terminal server on port 7681
worklet terminal --port 8080     # Use custom port
worklet terminal --proxy          # Enable service proxy

Features:

• Browser-based terminal with full TTY support
• Automatic container discovery
• Service proxy for accessing project services via subdomains

worklet link

Link external tools and services to your worklet configuration.

worklet link claude              # Enable Claude in worklet configuration
worklet link claude --force      # Force overwrite existing Claude settings

The link command adds necessary credential settings to your .worklet.jsonc configuration.

worklet credentials

Manage credentials for external services used by worklet.

worklet credentials claude       # Configure Claude API credentials

This command securely stores credentials that can be mounted into worklet containers when credentials.claude is enabled in your configuration.

worklet daemon

Manage the worklet daemon for service discovery and proxy routing.

worklet daemon start        # Start the daemon
worklet daemon stop         # Stop the daemon  
worklet daemon status       # Check daemon status

The daemon:

• Manages session registrations via Unix socket at ~/.worklet/worklet.sock
• Enables automatic service discovery
• Persists session state across daemon restarts

worklet ssh

Manage SSH credentials for use inside worklet containers.

worklet ssh setup               # Copy SSH keys to Docker volume
worklet ssh status              # Check SSH setup and test GitHub connectivity

This allows Git operations with private repositories to work seamlessly inside containers.

worklet cleanup

Clean up orphaned Docker resources from worklet sessions.

worklet cleanup                 # Clean up orphaned resources (preserves pnpm volumes)
worklet cleanup --force         # Clean up ALL orphaned resources

worklet code

Open a worklet session in VSCode using the Dev Containers extension.

worklet code                    # Open most recent session in VSCode
worklet code abc123             # Open specific session in VSCode

VSCode must be installed with the Dev Containers extension enabled.

worklet version

Show version information for the worklet CLI and daemon.

worklet version                 # Show CLI and daemon versions
worklet daemon version           # Show daemon version only

worklet refresh

Refresh session information to update service discovery.

worklet refresh                 # Refresh current session
worklet refresh abc123          # Refresh specific session
worklet refresh --all           # Refresh all active sessions

worklet forks

List all active worklet sessions with their accessible DNS names.

worklet forks                   # List all active sessions with service URLs
worklet forks --debug          # Show debug information

worklet projects

Manage worklet project history and settings.

worklet projects list           # List all projects in history
worklet projects clean          # Clean up project history

Configuration Examples

Basic Node.js Project

{
  "name": "my-node-app",
  "run": {
    "image": "node:18",
    "initScript": [
      "npm install"
    ]
  },
  "services": [
    {
      "name": "app",
      "port": 3000
    }
  ]
}

Python Development Environment

{
  "name": "python-ml",
  "run": {
    "image": "python:3.11",
    "environment": {
      "PYTHONUNBUFFERED": "1"
    },
    "initScript": [
      "pip install -r requirements.txt",
      "python -m nltk.downloader punkt"
    ]
  }
}

Multi-Service Application

{
  "name": "microservices",
  "services": [
    {
      "name": "frontend",
      "port": 3000,
      "subdomain": "app"
    },
    {
      "name": "api", 
      "port": 8080,
      "subdomain": "api"
    },
    {
      "name": "admin",
      "port": 3001,
      "subdomain": "admin"
    }
  ]
}

Docker Compose Project

{
  "name": "compose-app",
  "run": {
    "image": "worklet/base:latest",
    "composePath": "docker-compose.yml",
    "credentials": {
      "ssh": true
    }
  }
}

Private Repository Development

{
  "name": "private-project",
  "run": {
    "image": "node:18",
    "credentials": {
      "ssh": true,      // Mount SSH for Git operations
      "claude": true    // Mount Claude for AI assistance
    },
    "initScript": [
      "git config --global user.name 'Your Name'",
      "git config --global user.email 'your@email.com'",
      "npm install"
    ]
  }
}

Workflows

Development Workflow

# Start development with live reload
$ worklet run --mount npm run dev

# Your app is now running with:
# - Live code reloading
# - Full Docker-in-Docker support
# - Automatic service discovery

# Access your services:
# - http://app.my-project-12345.worklet.sh
# - http://api.my-project-12345.worklet.sh

VSCode Integration Workflow

# Start a development session
$ worklet run --mount

# Open the session in VSCode
$ worklet code

# VSCode opens with:
# - Full Dev Containers integration
# - Your extensions automatically installed
# - Terminal connected to the container
# - Git integration working seamlessly

Testing Workflow

# Run tests in isolated environment
$ worklet run npm test

# Run integration tests with Docker Compose
$ worklet run docker-compose run tests

# Run tests in temporary environment
$ worklet run --temp npm test

CI/CD Simulation

# Test your CI pipeline locally
$ worklet run ./scripts/ci.sh

# Full isolation ensures no side effects
# See exactly what your CI server sees

SSH Setup for Private Repositories

# One-time setup: configure SSH credentials
$ worklet ssh setup

# Check SSH is working
$ worklet ssh status

# Now your containers can clone private repos
$ worklet run git clone git@github.com:private/repo.git

Tips & Tricks

Shell Aliases

Add these to your shell configuration:

# Quick run commands
alias wr='worklet run'
alias wrm='worklet run --mount'
alias wrt='worklet run --temp'

# Terminal access
alias wt='worklet terminal'

Best Practices

1. Project Names: Set meaningful names in .worklet.jsonc for easier identification
2. Mount Mode: Use --mount for development, default mode for testing
3. Init Scripts: Keep them minimal for faster container startup
4. Services: Define all exposed ports for automatic discovery
5. Session Management: Use the interactive CLI (worklet) to manage sessions
6. Cleanup: Run worklet cleanup periodically to remove orphaned resources
7. SSH Setup: Run worklet ssh setup once for seamless Git operations
8. VSCode: Use worklet code for a full IDE experience with containers

Architecture

Worklet uses a client-server architecture:

• CLI: The main worklet command that users interact with
• Daemon: Background process for service discovery and session management
• Terminal Server: Web-based terminal and proxy server
• Docker Integration: Manages containers with proper isolation

For advanced proxy configuration and service routing, see the nginx proxy setup documentation.

Requirements

• Docker Desktop or Docker Engine
• macOS, Linux, or Windows with WSL2
• Go 1.21+ (for building from source)

Troubleshooting

Container Won't Start

Check Docker is running:

docker ps

Permission Denied

Ensure your user is in the docker group:

sudo usermod -aG docker $USER

Port Already in Use

Check what's using the port:

lsof -i :3000

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

Apache License 2.0. See the LICENSE file for details.