Skip to main content
Version: 1.5.0

thresh stop

Stop a running environment.

Synopsis​

thresh stop <environment-name>

Description​

The stop command stops a running environment:

Windows (WSL2):

  • Terminates the WSL distribution
  • All volumes and data preserved

Linux/macOS (containerd):

  • Stops the container
  • Volumes persist (can restart with thresh start)

Use when:

  • Freeing system resources
  • Temporarily disabling services
  • System is low on memory
Data Persistence

Stopping an environment does not delete any data. Volumes, configuration, and state are preserved. Use thresh start to resume.

Arguments​

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

Examples​

Basic Usage​

# Stop a running environment
PS C:\> thresh stop webserver
Stopping environment 'webserver'...
✅ Environment 'webserver' stopped successfully

Stop Multiple Environments​

# Stop all development environments
thresh stop web-frontend
thresh stop api-backend
thresh stop postgres-db

Data Persistence​

How It Works​

  1. Reads metadata - Loads port configuration from ~/.thresh/metadata/{env}.json
  2. Removes rules - Deletes netsh portproxy rules for each mapped port
  3. Validates - Ensures rules are fully removed
  4. Stops distribution - Terminates the WSL distribution

Example Cleanup​

Metadata: ~/.thresh/metadata/webserver.json

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

Removed Rules:

netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0
netsh interface portproxy delete v4tov4 listenport=8443 listenaddress=0.0.0.0

Verify Cleanup​

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

# Should not show rules for stopped environment

Linux & macOS Behavior​

On Linux and macOS, thresh stop simply stops the container/environment:

# No additional cleanup needed
thresh stop webserver

# Port mappings automatically released by Docker

Common Workflows​

Temporary Shutdown​

# Stop for maintenance
thresh stop webserver

# Make changes, update configuration...

# Resume
thresh start webserver

Resource Management​

# Free up memory by stopping unused environments
thresh list
thresh stop old-project-1
thresh stop old-project-2

# Check resource usage
thresh metrics

Before Windows Shutdown​

# Gracefully stop all environments before shutting down Windows
thresh stop web-app
thresh stop api-server
thresh stop database

# Prevents potential issues with WSL state

Troubleshooting​

Environment Not Running​

Issue: Environment is already stopped

thresh stop webserver
# Output: Environment 'webserver' is not running

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

Port Forwarding Cleanup Failed​

Issue: netsh rules not removed

# Manually remove port forwarding rules
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0

# Verify
netsh interface portproxy show all

Permission Denied​

Issue: Cannot stop WSL distribution

# Run PowerShell as Administrator
Start-Process powershell -Verb RunAs

# Retry stop command
thresh stop webserver

Metadata Not Found​

Issue: Warning about missing metadata

# Stop still works, but port forwarding cleanup is skipped
thresh stop webserver
# Warning: Metadata not found, skipping port forwarding cleanup

# Distribution still stops successfully

Data Persistence​

What Gets Preserved​

✅ Preserved when stopped:

  • Named volumes
  • Environment metadata
  • WSL configuration
  • User data
  • Application state

❌ Lost when stopped:

  • Running processes
  • In-memory data (tmpfs)
  • Network connections
  • Port forwarding rules (Windows)

Resume Example​

# Stop with data in database
thresh stop postgres-dev

# Later... restart
thresh start postgres-dev

# All database data is intact
wsl -d thresh-postgres-dev -- psql -U postgres -c "SELECT * FROM users;"

Best Practices​

Graceful Shutdown​

Stop services before stopping environment:

# Gracefully stop services first
wsl -d thresh-postgres-dev -- systemctl stop postgresql

# Then stop environment
thresh stop postgres-dev

Shutdown Scripts​

Create scripts for multiple environments:

PowerShell: stop-all-dev.ps1

# Stop all development environments gracefully
$environments = @("web-frontend", "api-backend", "postgres-db")

foreach ($env in $environments) {
    Write-Host "Stopping $env..."
    thresh stop $env
}

Write-Host "All environments stopped"

Check Before Stopping​

Verify environment is stopped:

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

# If running, stop it
if ((wsl -l -v | findstr "thresh-webserver.*Running")) {
    thresh stop webserver
}

Automated Cleanup​

Schedule regular cleanup of unused environments:

# Stop environments not used in 7 days
Get-ChildItem ~/.thresh/metadata/*.json | 
    Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-7)} |
    ForEach-Object {
        $envName = $_.BaseName
        thresh stop $envName
    }

Performance Impact​

Memory Release​

Stopping environments frees:

  • WSL2 Memory: ~500 MB - 4 GB per environment
  • CPU: Background processes stopped
  • Disk I/O: No active disk operations

Quick Comparison​

# Check memory before
wsl --shutdown
wsl -d thresh-postgres-dev --exec free -h

# Stop environment
thresh stop postgres-dev

# Memory is released to Windows

Reference​

WSL Distribution States​

StateDescriptionCan Stop?
RunningEnvironment is active✅ Yes
StoppedEnvironment is inactive❌ Already stopped
Not FoundEnvironment doesn't exist❌ Not found

Exit Codes​

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

Metadata File​

Port forwarding configuration read from:

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

Next Steps​