Introduction to thresh
AI-powered container environment manager for Windows, Linux, and macOS
🖧 Agent Mode is here! Connect any thresh node to a centralized Thresh Hub for real-time fleet visibility, live metrics, and centralized management — all over SignalR WebSocket.
# Register and connect to your Thresh Hub in one command
thresh agent start --hub https://hub.example.com --node my-workstation
thresh is a .NET 10 Native AOT command-line tool that provisions container-based development environments using AI-generated blueprints. Create development environments in seconds with natural language prompts, and optionally connect nodes to a centralized Thresh Hub for fleet-wide visibility and management.
Architecture Overview
thresh provides isolated development environments using lightweight containers across multiple platforms:
Key Features
- 🌍 Multi-Platform - Windows/WSL2, Linux/Docker/nerdctl, macOS/containerd
- 🤖 AI-Powered - GitHub Copilot CLI integration for intelligent blueprint generation
- 🌐 Port Mapping - Automatic port forwarding for network services (v1.5.0)
- 📦 Persistent Volumes - Data persistence across environment lifecycle (v1.5.0)
- 🗄️ Database Optimization - WSL configuration profiles fix Plan9 filesystem issues (v1.5.0)
- 🖧 Agent Mode - Connect nodes to Thresh Hub for fleet management (v1.6.0)
- ⚡ Parallel Creation - Create multiple environments simultaneously (10x faster)
- 📦 Built-in Blueprints - Alpine, Ubuntu, Debian, Python, Node.js, and more
- 🗑️ Blueprint Management - List, generate, and delete blueprints
- 💬 Interactive AI Chat - Streaming responses for blueprint assistance
- 🚀 Native Binary - No .NET runtime required (5-13 MB)
- 📊 System Metrics - Monitor CPU, memory, storage, and container usage
- 🔧 MCP Server - Model Context Protocol for VS Code, Cursor, Windsurf
Getting Started by Platform
Choose your platform to get started:
🪟 Windows
Get started with thresh on Windows 11 using WSL 2
Requirements:
- Windows 11
- WSL 2 enabled
🐧 Linux
Get started with thresh on Linux using Docker or nerdctl
Requirements:
- Docker or nerdctl/containerd
🍎 macOS
Get started with thresh on macOS (Apple Silicon) using containerd
Requirements:
- macOS (Apple Silicon M1/M2/M3)
- containerd or Docker Desktop
Beta Support
Quick Example
# Install thresh (platform-specific, see guides above)
# Authenticate with GitHub Copilot CLI
copilot
# Then: /login
# List available blueprints
thresh blueprint list
# Create environment with networking and storage (v1.5.0)
thresh blueprint generate "PostgreSQL with persistent volumes and port mapping"
# Provision with automatic configuration
thresh up postgres-dev
# Access from host
psql -h localhost -p 5432 -U postgres
# Generate custom blueprint with AI
thresh blueprint generate "Python ML environment with Jupyter" --output python-ml
# Start interactive chat
thresh chat
What's New in v1.6.0
🖧 Agent Mode & Hub Connectivity
Connect any thresh node to a centralized Thresh Hub instance for real-time fleet-wide visibility and management. Agent Mode is the foundational feature for multi-node workflows.
# Start the agent and connect to your hub
thresh agent start --hub https://hub.example.com --node-name my-workstation
# Check connection health
thresh agent status
# Update hub URL without restarting
thresh agent config set hub-url https://new-hub.example.com
Transport options:
| Transport | Protocol | Use Case |
|---|---|---|
signalr | WebSocket (WS/WSS) | Default — low-latency bidirectional |
http | HTTP Long Polling | Fallback for restricted networks |
What the Hub sees per node:
- ✅ Live online / offline status
- 📊 Real-time CPU, memory, storage metrics
- 🧱 Running environments list
- 🏷️ Custom node name and region tags
- 🔗 Agent version and platform info
Coming soon in v1.6.x: remote command dispatch, fleet blueprints, RBAC access control, and node group policies.
Agent CLI reference → | Blog post →
What's New in v1.5.0
🌐 Port Mapping & Networking
Map host ports to container services with automatic forwarding:
{
"ports": ["8080:80", "5432:5432"],
"network": "bridge",
"hostname": "webapp.local"
}
Features:
- Automatic port forwarding on Windows (netsh)
- Multiple port mappings
- IP binding and protocol selection
- Exposed ports for inter-container communication
📦 Persistent Volumes
Never lose data with three types of storage:
{
"volumes": [
{"name": "pgdata", "mountPath": "/var/lib/postgresql/data"}
],
"bindMounts": [
{"source": "C:\\projects", "target": "/app"}
],
"tmpfs": [
{"mountPath": "/tmp", "size": "512m"}
]
}
Features:
- Named volumes persist across recreation
- Bind mounts for live code editing
- Tmpfs for fast temporary storage
🗄️ WSL Configuration Profiles
Fix database permission errors with built-in profiles:
{
"wslConfig": "database" // Fixes Plan9 filesystem issues
}
Built-in profiles:
database- PostgreSQL, MySQL, MongoDB, Redisdocker- Docker daemon auto-startweb-server- Nginx/Apache auto-startsystemd- Basic systemd enablementminimal- Maximum isolationdevelopment- Full development features
🔄 Lifecycle Management
Start and stop environments with networking:
# Start with automatic port forwarding
thresh start webserver
# Stop and cleanup
thresh stop webserver
Platform Support
| Platform | Runtime | Binary Size | Compression | Status |
|---|---|---|---|---|
| Windows 11 | WSL2 | ~5 MB | UPX | ✅ Supported |
| Linux | Docker, nerdctl, containerd | ~5 MB | UPX | ✅ Supported |
| macOS (M1/M2/M3) | containerd, Docker | ~13 MB | None* | ✅ Beta |
*macOS binaries are uncompressed to preserve Apple code signing and notarization.
Documentation
- 📚 Windows Guide - Complete Windows setup
- 🐧 Linux Guide - Complete Linux setup
- 🍎 macOS Guide - Complete macOS setup (Beta)
- 🔧 CLI Reference - Complete command documentation
- 🤖 MCP Integration - VS Code, Cursor, Windsurf setup
- 📖 Tutorials - Step-by-step guides
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Repository: GitHub
Next Steps
Choose your platform to get started:
Happy provisioning! 🚀