Skip to main content

Workspace Architecture

You're debugging a backend API. Meanwhile, a frontend colleague needs you to look at a CSS issue. And there's an infrastructure alert to deal with.

In most AI tools, you'd either juggle everything in one messy conversation, or repeatedly start new chats and lose context. In Helix, you just open three Workspaces, each fully independent, zero interference.

Workspace is the fundamental execution boundary in Helix.

Why Workspace Isolation Matters​

Engineers don't work on just one thing at a time. Without isolation, these problems keep recurring:

  • Discussing two projects in the same conversation — AI gives code suggestions for the wrong repo
  • Tool configuration conflicts — frontend and backend projects need different shell environments and LSP setups
  • Model selection confusion — DeepSeek is more cost-effective for code generation, Claude is more accurate for architecture review, but switching is painful
  • Context cross-contamination — backend debugging log output interferes with frontend code analysis

Workspaces solve these problems at the root: each Workspace is a fully independent execution sandbox.

What Each Workspace Independently Owns​

Isolation DimensionDescription
Session HistoryEach Workspace maintains all its own conversations and message history
Context StateCache and Compact strategies operate independently per Workspace
Tool ConfigurationShell, filesystem, LSP, and other built-in MCP servers are instantiated per Workspace
Model & ProfileEach Workspace can choose different default models and system prompts
MCP ServersUser-defined MCP servers are bound per Workspace
SubAgent TasksSubAgents run within their parent Workspace's boundaries

This means: switching Workspaces is like switching to a completely different workstation — clean, fast, with zero context residue.

Local and Remote Workspaces​

Workspaces aren't limited to local directories. Helix supports two target types:

Local Workspace​

Points to a project directory on your machine. Built-in MCP servers (Shell, filesystem, LSP) operate directly on local files and terminal.

This is the most common usage — open your code repo and start working.

Remote Workspace​

Connects to a remote server via SSH, executing commands and file operations on the remote machine while UI interaction and session management stay local.

Use cases:

  • Production environment debugging on servers
  • Model training monitoring on GPU machines
  • Remote codebase work without local environment dependencies

You can have a local Workspace and a remote Workspace open simultaneously in Helix UI, operating on two completely different environments with the exact same interaction model.

Workspace Lifecycle​

Each Workspace has a well-defined lifecycle:

Create / Connect
    │
    ▼
Lazy-load Session Manager
    │  (initialized on first use, avoiding startup overhead)
    │
    ▼
Active Use
    │  ├─ Multiple sessions in parallel
    │  ├─ Tool calls and SubAgent execution
    │  └─ Cache / Compact continuously maintaining context
    │
    ├─ User disconnects manually
    │       ▼
    │    Save state, release resources
    │
    └─ No activity for extended period
            ▼
         Idle timeout (default 30 minutes) → auto-close
         Re-loads on next connection

Key design choices:

  • Lazy loading — Workspaces don't initialize all resources on creation; Session Manager and MCP servers load on first use
  • Idle timeout — default 30-minute inactivity auto-close, freeing memory and connection resources
  • State persistence — session history and context fully restore on reconnection after disconnect

Worktree Binding: Protecting the Main Branch​

When an AI Agent needs to modify code, operating directly on the main branch is risky. Helix provides a Git Worktree binding mechanism:

  • Write operations automatically execute on isolated git worktree branches
  • The main branch stays clean, unaffected by Agent modifications
  • After the Agent finishes, you can review branch changes and decide whether to merge

This is especially important when multiple Agents modify the same repository in parallel — each Agent works on its own branch, avoiding conflicts.

Agent Profiles: Preset Work Templates​

Different task types need different Agent configurations. Helix lets you preset work templates for Workspaces through Agent Profiles (YAML format):

# Example: Code review specialist profile
name: code-reviewer
model: claude-sonnet-4
system_prompt: |
  You are a meticulous code reviewer focused on security,
  performance, and maintainability. Always explain the
  reasoning behind your suggestions.
thinking_enabled: true
mcp_servers:
  - serena-lsp
  - shell
  - filesys

You can select different Profiles for different Workspaces — one for code generation, another for code review, a third for documentation writing.

Practical Usage Patterns​

Pattern 1: Multi-Project Parallel Work​

The most common pattern. One Workspace per project, no interference.

Workspace A: frontend-app
  └─ Model: Claude Sonnet · Profile: Frontend Dev
  └─ Session: "Implement new user settings page"

Workspace B: backend-api  
  └─ Model: DeepSeek · Profile: Backend Dev
  └─ Session: "Optimize database query performance"

Workspace C: infra-config
  └─ Model: GPT-4o · Profile: Ops Analysis
  └─ Session: "Analyze deployment log anomalies"

Pattern 2: Local + Remote Side-by-Side​

When you need to work on local code and a remote server simultaneously:

Workspace A: Local code repository
  └─ Modify code, run tests

Workspace B: Remote production server (SSH)
  └─ Analyze logs, check configs, verify deployment

Pattern 3: Different Security Domains​

In enterprise scenarios, different projects may have different security requirements:

Workspace A: Internal core services (self-hosted model + strict MCP permissions)
Workspace B: Open source contribution project (cloud model + full toolset)

Relationship to Other Capabilities​

CapabilityRelationship to Workspace
Multi-AgentSubAgents run within their parent Workspace, never crossing Workspace boundaries
Context ManagementCache and Compact are isolated per Workspace, no cross-interference
Multi-ModelEach Workspace can independently choose models and Profiles
MCP ToolsBuilt-in MCP servers are instantiated per Workspace, user MCPs bound per Workspace