Workspaces

Workspaces are isolated development environments that run in Docker containers. Each workspace provides a complete development setup with IDE, terminal, and all necessary tools.

Overview

A workspace includes:

• Container: Docker container with pre-configured tools
• IDE: VS Code Server or JetBrains Gateway
• Storage: Persistent volumes for data
• Network: Isolated network with exposed ports

Workspace Types

Persistent Workspace

Long-lived workspaces for ongoing projects.

devenv create myproject --template bun-typescript

Characteristics:

• Data persists across container restarts
• Survives system reboots
• Ideal for active development
• No automatic cleanup

Temporary Workspace

Short-lived workspaces for quick tasks.

devenv create quicktest --type temporary

Characteristics:

• Data deleted when stopped
• Perfect for testing and experiments
• Lightweight resource usage
• Auto-cleanup on stop

Agent Workspace

Workspaces created by AI agents for automated tasks.

Characteristics:

• Configurable TTL (Time-to-Live)
• Managed via agent-backend API
• Automatic port allocation
• Session-based lifecycle

Creating Workspaces

Via CLI

devenv create myproject

devenv create myproject --template node-typescript

devenv create myproject \
  --git https://github.com/user/repo.git \
  --branch main

Via API

curl -X POST http://localhost:3100/api/workspaces \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myproject",
    "template": "bun-typescript",
    "type": "persistent"
  }'

Via MCP

// MCP tool call
{
  "name": "create_workspace",
  "arguments": {
    "name": "myproject",
    "template": "bun-typescript"
  }
}

Templates

bun-typescript

Default template optimized for Bun and TypeScript.

Includes:

• Bun v1.x runtime
• TypeScript configured
• ESLint + Prettier
• VS Code extensions for TypeScript

Best for: Modern TypeScript projects, APIs, full-stack apps

node-typescript

Node.js with TypeScript support.

Includes:

• Node.js 22 LTS
• TypeScript configured
• pnpm package manager
• Common Node.js tools

Best for: Node.js applications, npm packages

custom

Minimal base for custom setups.

Includes:

• Base development tools
• Zsh with Oh My Posh
• Git, curl, wget

Best for: Custom toolchains, specialized environments

Workspace Lifecycle

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  creating   │ -> │   running   │ -> │   stopped   │
└─────────────┘    └─────────────┘    └─────────────┘
                          |                  |
                          v                  v
                   ┌─────────────┐    ┌─────────────┐
                   │    error    │    │  destroyed  │
                   └─────────────┘    └─────────────┘

States

Accessing Workspaces

Code-Server (VS Code)

Access VS Code in your browser:

http://localhost:8443

Features:

• Full VS Code experience
• Extensions support
• Integrated terminal
• File explorer

SSH

Connect via terminal:

ssh root@localhost -p 2222

Or using the CLI:

devenv shell myproject

RDP (Remote Desktop)

For full desktop access:

rdp://localhost:3389

Use Windows Remote Desktop, Remmina, or Microsoft Remote Desktop.

JetBrains Gateway

Connect with JetBrains IDEs:

1. Open JetBrains Gateway
2. New Connection → SSH
3. Host: localhost, Port: 2222
4. Select your IDE (IntelliJ, WebStorm, etc.)

Port Management

Workspaces automatically allocate ports from these ranges:

Checking Ports

devenv status myproject

Output:

Workspace: myproject
Status: running
Ports:
  Code-Server: 8443
  SSH: 2222
  RDP: 3389

Custom Ports

Configure in your environment:

devenv config --set ports.codeServer 9000

Storage & Volumes

Each workspace has these volumes:

Backup Workspace

# Export workspace data
devenv backup myproject --output ./myproject-backup.tar.gz

Restore Workspace

# Restore from backup
devenv restore myproject --from ./myproject-backup.tar.gz

Multi-Workspace Setup

Run multiple workspaces simultaneously:

# Create multiple workspaces
devenv create frontend --template bun-typescript
devenv create backend --template node-typescript
devenv create database --template custom

# List all
devenv list

Output:

NAME       STATUS    PORT   TEMPLATE
frontend   running   8443   bun-typescript
backend    running   8444   node-typescript
database   running   8445   custom

Resource Limits

Configure container resources:

devenv create myproject \
  --memory 4g \
  --cpus 2

Defaults:

• Memory: 4GB
• CPUs: 2 cores
• Disk: No limit (uses host disk)

Cleanup

Stop Workspace

devenv stop myproject
# Container stopped, data preserved

Destroy Workspace

devenv destroy myproject
# Container AND data removed

Cleanup All Stopped

# Remove all stopped workspaces
devenv prune

Troubleshooting

Workspace Won't Start

# Check container logs
devenv logs myproject --tail 100

# Check Docker status
docker ps -a | grep myproject

Port Conflicts

# Find what's using the port
lsof -i :8443

# Use different port
devenv config --set ports.codeServer 9443

Out of Disk Space

# Check Docker disk usage
docker system df

# Clean unused images
docker image prune -a

Connection Refused

1. Verify workspace is running: devenv status myproject
2. Check firewall rules
3. Verify Docker network: docker network ls

Best Practices

1. Use templates - Start with a template that matches your project
2. Name meaningfully - Use descriptive workspace names
3. Backup important data - Regularly backup persistent workspaces
4. Clean up - Destroy unused workspaces to free resources
5. Use appropriate type - Temporary for experiments, persistent for real work

Related

• DevEnv CLI - Command-line reference
• Agent Backend API - REST API documentation
• Configuration - System configuration