Skip to content

Managing Workspaces

Jump to bottom
Andrew den Hertog edited this page Dec 3, 2025 · 1 revision

Managing Workspaces

This guide covers everything you need to know about creating, configuring, and managing your development workspaces.

Table of Contents

What is a Workspace?

A workspace is your personal cloud-based development environment. Each workspace:

  • Runs code-server (VS Code in the browser)
  • Has persistent storage for your projects
  • Can be started, stopped, and restarted on demand
  • Is accessible via a unique URL
  • Requires a password for access
  • Belongs to a specific group
  • Uses resources from its group's quota

Workspace Characteristics

Characteristic Description
Persistent Your files remain even when stopped
Isolated Each workspace is separate and secure
On-Demand Start only when needed to save resources
Configurable Choose CPU, memory, and storage
Accessible Access from any browser, anywhere

Creating Workspaces

Prerequisites

Before creating a workspace:

  • ✅ You must belong to at least one group
  • ✅ The group must have available resources
  • ✅ You must have Member role or higher

Creation Steps

  1. Navigate to Workspaces

    • Click Workspaces in the main navigation
    • Click Create New Workspace button

  2. Fill in Basic Information

    Name (required)

    • Choose a descriptive name
    • Examples: "Frontend Development", "API Testing", "ML Training"
    • Must be unique within your workspaces

    Description (optional)

    • Add notes about the workspace purpose
    • Examples: "React app for customer portal", "Python data analysis"

    Group (required)

    • Select which group this workspace belongs to
    • You can only choose groups you're a member of
    • Workspace will use this group's resources

  3. Choose Resources

    Option A: Resource Tier (Recommended)

    Select a predefined tier:

    Tier CPU Memory Storage Use Case
    Single User 0.5 cores 1 GB 10 GB Light coding, config editing
    Small Team 2 cores 4 GB 50 GB Most development work
    Enterprise 4 cores 8 GB 100 GB Heavy builds, databases, ML

    Option B: Custom Resources (Advanced)

    Specify exact resources:

    • CPU: e.g., "1", "2", "4"
    • Memory: e.g., "2Gi", "4Gi", "8Gi"
    • Storage: e.g., "20Gi", "50Gi", "100Gi"

  4. Advanced Options (Optional)

    Workspace Image

    • Default: System default image (usually latest)
    • Custom: Specify a different code-server image
    • Format: ghcr.io/user/image:tag
    • Most users should use the default

  5. Create

    • Click Create Workspace
    • Wait for confirmation
    • IMPORTANT: Save the password shown!

After Creation

What Happens:

  • Workspace is created in "Stopped" state
  • Kubernetes resources are provisioned
  • Persistent volume is allocated
  • Workspace is ready to start

Your Password:

Password: abc123xyz789...
  • Save this securely!
  • You'll need it to access the workspace
  • It cannot be recovered if lost
  • Store in password manager

Resource Allocation:

  • Resources are reserved in the group quota
  • Even stopped workspaces count toward storage quota
  • Running workspaces use CPU and memory quota

Workspace States

Your workspace transitions through different states:

Stopped ⏹️

What it means:

  • Workspace is not running
  • No CPU or memory used
  • Files are preserved in storage
  • Storage quota is still used

When to use:

  • End of workday
  • When not actively developing
  • To free resources for teammates

How to get here:

  • Click Stop button
  • Wait for transition (5-10 seconds)

Starting 🔄

What it means:

  • Workspace is booting up
  • Pod is being scheduled
  • Container is starting
  • Usually takes 30-60 seconds

What to do:

  • Wait patiently
  • Don't click Start again
  • Monitor status indicator

Running ✅

What it means:

  • Workspace is fully operational
  • Accessible via Open button
  • Using group CPU and memory quota
  • Ready for development work

What you can do:

  • Click Open to access
  • View logs
  • Monitor resource usage
  • Stop or restart

Stopping 🔄

What it means:

  • Workspace is shutting down
  • Containers are terminating
  • Files being synced to persistent storage
  • Usually takes 5-10 seconds

What happens:

  • Graceful shutdown initiated
  • Processes are terminated
  • Pod is removed
  • Storage is preserved

Error ❌

What it means:

  • Something went wrong
  • Workspace failed to start
  • Pod encountered an error
  • Intervention needed

What to do:

  1. Check workspace logs
  2. Try restarting
  3. Verify group has resources
  4. Contact administrator if persists

Pending ⏳

What it means:

  • Workspace is waiting for resources
  • Pod cannot be scheduled
  • Insufficient cluster capacity

What to do:

  1. Wait a few minutes
  2. Check group resource usage
  3. Stop other workspaces
  4. Contact administrator

Controlling Workspaces

Starting a Workspace

From Workspace List:

  1. Find your workspace
  2. Click Start button
  3. Wait for "Running" status
  4. Click Open when ready

From Workspace Details:

  1. Click workspace name
  2. Click Actions → Start
  3. Monitor status

Typical Start Time: 30-60 seconds

What happens during start:

  • Kubernetes schedules pod
  • Container image is pulled (if not cached)
  • Storage volume is mounted
  • Code-server starts
  • Health checks pass

Stopping a Workspace

Why stop a workspace:

  • Free resources for others
  • Reduce group resource usage
  • End of workday
  • Switching to different workspace

How to stop:

  1. Save your work in the workspace first!
  2. In Codex Web, click Stop button
  3. Wait for "Stopped" status

What is preserved:

  • All files in /workspace/.codex-projects
  • Installed VS Code extensions
  • Code-server settings

What is lost:

  • Running processes
  • Terminal sessions
  • Unsaved editor changes (if not saved)
  • Files outside persistent directory

Restarting a Workspace

When to restart:

  • Workspace is unresponsive
  • Need a clean environment
  • After configuration changes
  • Troubleshooting issues

How to restart:

  1. Click Restart button
  2. Workspace stops and starts automatically
  3. Wait for "Running" status

What happens:

  • Workspace is stopped
  • Resources are released
  • Workspace starts fresh
  • Storage is preserved

Syncing Workspace State

If workspace status seems incorrect:

  1. Click on workspace
  2. Click Sync button
  3. System fetches current Kubernetes state
  4. Status is updated

When to use:

  • Status seems stuck
  • After manual Kubernetes operations
  • Discrepancy between UI and reality

Updating Workspaces

Editable Fields

Name and Description:

  1. Click workspace name
  2. Click Edit button
  3. Update name or description
  4. Click Save

Non-Editable Fields:

  • Group assignment (cannot change)
  • Resource allocation (create new workspace)
  • Image (for running workspaces)
  • Storage size (fixed at creation)

Changing Resources

To change workspace resources:

  1. Save/backup your work
  2. Create new workspace with desired resources
  3. Copy files to new workspace
  4. Delete old workspace

Note: In-place resource updates are not supported to maintain stability.

Monitoring Workspaces

Workspace List View

Quick Status:

  • Name and description
  • Current state (icon and color)
  • Group it belongs to
  • Last accessed time
  • Quick actions (Start/Stop/Open)

Filtering:

  • View all workspaces
  • Filter by group
  • Filter by status
  • Sort by name, date, status

Workspace Detail View

Click a workspace to see:

Overview Tab:

  • Full workspace information
  • Current status
  • Creation and update times
  • URL and access info
  • Resource allocation

Resources Tab:

  • CPU usage (current)
  • Memory usage (current)
  • Storage usage
  • Visual usage graphs
  • Comparison to allocated amounts

Logs Tab:

  • Recent container logs
  • Error messages
  • Startup logs
  • Filter by time
  • Download logs

Health Tab:

  • Pod health status
  • Container health
  • Readiness status
  • Recent health check results

Resource Monitoring

Viewing Usage:

  1. Click on a running workspace
  2. Go to Resources tab
  3. See real-time usage:
CPU:     1.2 / 2.0 cores (60%)
Memory:  2.8 / 4.0 GB (70%)
Storage: 15 / 50 GB (30%)

Understanding Metrics:

  • Current Usage: What's being used right now
  • Allocated: What the workspace can use maximum
  • Percentage: Usage relative to allocation

When to Worry:

  • CPU at 100%: Workspace may be slow
  • Memory at 90%+: Risk of out-of-memory errors
  • Storage at 95%+: Won't be able to save new files

Viewing Logs

Accessing Logs:

  1. Click workspace name
  2. Go to Logs tab
  3. View recent output

Log Contents:

  • Container startup messages
  • Code-server initialization
  • Application errors
  • Connection logs

Using Logs:

  • Troubleshoot startup failures
  • Debug connection issues
  • Identify errors
  • Monitor workspace health

Download Logs:

  • Click Download to save logs
  • Useful for sharing with support
  • Includes timestamp information

Deleting Workspaces

Before You Delete

⚠️ WARNING: Deletion is permanent and immediate!

Before deleting:

  • ✅ Save important work to git
  • ✅ Download any needed files
  • ✅ Stop the workspace
  • ✅ Verify you're deleting the correct workspace
  • ✅ Check with team if others depend on it

Deletion Process

  1. Stop the workspace (recommended)
  2. Click Delete button
  3. Confirm deletion in dialog
  4. Workspace is immediately deleted

What gets deleted:

  • All workspace files
  • Persistent storage
  • Kubernetes resources
  • Configuration
  • Logs
  • Everything!

What is NOT deleted:

  • Code in external git repositories
  • Files you downloaded locally
  • Your user account
  • Group membership

Who Can Delete

You can delete:

  • Workspaces you created

Group admins can delete:

  • Any workspace in their group

Platform admins can delete:

  • Any workspace on the platform

After Deletion

Resources Released:

  • CPU quota returned to group
  • Memory quota returned to group
  • Storage quota returned to group
  • Pod count decreases

Changes Take Effect:

  • Immediately
  • Group resources available for new workspaces
  • Workspace disappears from UI

Workspace Best Practices

Resource Management

Right-Sizing:

  • Start with smaller tiers
  • Monitor actual usage
  • Upgrade if consistently hitting limits
  • Don't over-provision

Efficient Usage:

  • Stop workspaces when done
  • Delete unused workspaces
  • Share resources fairly with team
  • Monitor group quota impact

Data Management

Version Control:

  • Use git for all important code
  • Push changes regularly
  • Don't rely solely on workspace storage
  • Keep remote backups

File Organization:

  • Keep all work in /workspace/.codex-projects
  • Organize by project
  • Include README files
  • Document setup steps

Regular Maintenance:

  • Clean up old files
  • Remove unused dependencies
  • Clear logs and caches
  • Keep storage usage reasonable

Naming and Documentation

Clear Names:

  • Use descriptive workspace names
  • Include project or purpose
  • Examples:
    • ✅ "Customer Portal Frontend"
    • ✅ "Data Pipeline Development"
    • ❌ "Workspace 1"
    • ❌ "Test"

Good Descriptions:

  • Note the purpose
  • List main technologies
  • Include relevant links
  • Document special setup

Security

Password Management:

  • Store passwords securely
  • Use password manager
  • Don't share passwords
  • Don't commit passwords to git

Access Control:

  • Only share workspace URLs with authorized users
  • Log out when done on shared computers
  • Use workspace-level authentication
  • Report suspicious activity

Troubleshooting

Workspace Won't Start

Symptoms:

  • Stuck in "Starting" state
  • Changes to "Error" state
  • Never reaches "Running"

Solutions:

  1. Check group has available resources
  2. View workspace logs for errors
  3. Try stopping and starting again
  4. Verify group quota isn't exceeded
  5. Contact administrator

Workspace is Slow

Possible Causes:

  • Resource limits reached
  • Group quota nearly full
  • Heavy workload
  • Insufficient tier

Solutions:

  1. Check resource usage in Resources tab
  2. Stop other workspaces
  3. Restart the workspace
  4. Consider higher resource tier
  5. Close unused editor tabs/terminals

Can't Access Workspace

Check:

  • Workspace status is "Running"
  • URL is correct
  • Password is correct
  • Network connection is stable
  • Firewall/proxy settings

Try:

  1. Restart workspace
  2. Check logs for errors
  3. Try different browser
  4. Clear browser cache
  5. Contact administrator

Password Issues

Problem: Lost workspace password

Solution:

  • Passwords cannot be recovered
  • Create new workspace
  • Copy files from old workspace (if accessible)
  • Delete old workspace

Prevention:

  • Save passwords in password manager
  • Document passwords securely
  • Keep backup of critical access info

Next Steps

← Understanding Groups | Accessing Your Workspace →

Clone this wiki locally