Skip to main content
Version: Next

thresh start

Start a stopped environment.

Synopsis​

thresh start <environment-name>

Description​

The start command starts a stopped environment:

Windows (WSL2):

  • Starts the WSL distribution
  • Services automatically accessible via localhost (WSL2 automatic port forwarding)

Linux/macOS (containerd):

  • Starts the container
  • Port mappings defined in blueprint are restored

This is useful after:

  • Manual thresh stop command
  • System shutdown or restart
  • wsl --shutdown (Windows only)

Arguments​

ArgumentRequiredDescription
<environment-name>YesName of the environment to start

Examples​

Basic Usage​

# Start a stopped environment
PS C:\> thresh start webserver
Starting environment 'webserver'...
✅ Environment 'webserver' started successfully

# Access services via localhost (automatic WSL2 forwarding)
PS C:\> curl http://localhost:8080

Port Access​

Windows (WSL2)​

WSL2 automatically forwards all listening ports to Windows localhost:

{
  "EnvironmentName": "webserver",
  "Ports": ["8080:80", "8443:443"],
  "Network": "bridge"
}

Generated Rules:

netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=80 connectaddress=172.24.123.45
netsh interface portproxy add v4tov4 listenport=8443 listenaddress=0.0.0.0 connectport=443 connectaddress=172.24.123.45

Verify Port Forwarding​

# Check all Windows port forwarding rules
netsh interface portproxy show all

# Test connectivity
curl http://localhost:8080

Linux & macOS Behavior​

On Linux and macOS, thresh start simply starts the container/environment:

# No additional port forwarding needed
thresh start webserver

# Ports work via native Docker networking
curl http://localhost:8080

Common Workflows​

After Windows Restart​

# Windows restarted, WSL port forwarding is lost
thresh start webserver
# ✓ Port forwarding automatically restored

After wsl --shutdown​

# Manual WSL shutdown
wsl --shutdown

# Restart environment with networking
thresh start postgres-dev
# ✓ Environment started with port forwarding

Multiple Environments​

# Start multiple environments
thresh start web-frontend
thresh start api-backend
thresh start postgres-db

# All port mappings restored for each environment

Troubleshooting​

Port Already in Use​

Issue: Port is already bound on Windows

# Find process using the port
netstat -ano | findstr :8080

# Kill the process
taskkill /PID 12345 /F

# Retry start
thresh start webserver

Port Forwarding Not Working​

Issue: Services not accessible from Windows

# 1. Check WSL IP
wsl -d thresh-webserver -- hostname -I

# 2. Verify service is running inside WSL
wsl -d thresh-webserver -- ss -tlnp | grep :80

# 3. Test from inside WSL
wsl -d thresh-webserver -- curl http://localhost:80

# 4. Check Windows firewall
# Ensure port 8080 is allowed

# 5. Manually verify port forwarding rules
netsh interface portproxy show all

Environment Already Running​

Issue: Environment is already started

thresh start webserver
# Output: Environment 'webserver' is already running

# Check status
wsl -l -v | findstr thresh-webserver

Metadata Not Found​

Issue: Environment metadata missing

# Check if metadata exists
ls ~/.thresh/metadata/webserver.json

# If missing, port forwarding won't be configured
# Recreate environment from blueprint:
thresh destroy webserver -y
thresh up webserver

Best Practices​

Automatic Startup​

Create a Windows Task Scheduler task to auto-start environments on login:

PowerShell Script: start-dev-envs.ps1

# Auto-start development environments
thresh start web-frontend
thresh start api-backend
thresh start postgres-db

Task Scheduler:

  • Trigger: At log on
  • Action: PowerShell -File "C:\scripts\start-dev-envs.ps1"

Health Checks​

Verify services are accessible after starting:

# Start environment
thresh start webserver

# Wait for service to be ready
Start-Sleep -Seconds 3

# Health check
$response = Invoke-WebRequest -Uri "http://localhost:8080/health" -UseBasicParsing
if ($response.StatusCode -eq 200) {
    Write-Host "✓ Web server is healthy"
}

Startup Scripts​

Run initialization commands after starting:

# Start environment
thresh start postgres-dev

# Run migrations
wsl -d thresh-postgres-dev -- psql -U postgres -f /app/migrations/001_init.sql

Reference​

Metadata File Location​

  • Windows: C:\Users\<username>\.thresh\metadata\{environmentName}.json
  • Linux: /home/<username>/.thresh/metadata/{environmentName}.json
  • macOS: /Users/<username>/.thresh/metadata/{environmentName}.json

Metadata Schema​

{
  "EnvironmentName": "string",
  "Ports": ["hostPort:containerPort"],
  "Expose": ["port"],
  "Network": "bridge|host|none",
  "Hostname": "string",
  "Volumes": [...],
  "BindMounts": [...],
  "Tmpfs": [...]
}

Exit Codes​

CodeMeaning
0Success
1General error
4Environment not found
5Failed to apply port forwarding

Next Steps​