Workspaces

Understanding Atlas workspaces - your AI agent environments

Workspaces

Workspaces are the fundamental building blocks of Atlas. Think of a workspace as a self-contained environment where your AI agents live, work, and collaborate.

What is a Workspace?

A workspace is:

• 🏠 A directory containing a workspace.yml configuration file
• 🤖 Home to one or more AI agents
• 📋 A collection of jobs and workflows
• 🔧 A set of tools and capabilities
• 🧠 An isolated memory context

Workspace Structure

my-workspace/
├── workspace.yml       # Main configuration
├── agents/            # Custom agent definitions (optional)
├── jobs/              # Complex job definitions (optional)
└── .atlas/            # Atlas metadata (auto-generated)

Creating a Workspace

Create a new workspace in seconds:

# Create a new directory
mkdir my-project && cd my-project

# Initialize the workspace
atlas init

# Or specify a name
atlas init "My AI Project"

This creates a workspace.yml file with a basic structure:

version: "1.0"

workspace:
  name: "my-project"
  description: "AI-powered project workspace"

agents: {}
signals: {}
jobs: {}

Workspace Identity

Each workspace has:

• ID: Auto-generated unique identifier
• Name: Human-readable name
• Description: What the workspace does

Workspace Lifecycle

Registration

When you run Atlas commands in a workspace directory, it’s automatically registered with the daemon:

# Automatic registration
atlas signal list  # Registers and lists signals

# Manual registration
atlas workspace register

Activation

The Atlas daemon loads your workspace configuration and makes it available for:

• Signal processing
• Job execution
• Agent coordination
• Memory operations

Updates

Changes to workspace.yml are detected automatically. The daemon reloads configurations intelligently using SHA-256 hashing for efficiency.

Workspace Isolation

Security

• Each workspace runs in isolated Deno Web Workers
• Agents cannot access other workspaces
• Resource limits prevent runaway processes

Memory

• Workspaces have their own memory contexts
• Agents within a workspace can share memory
• Cross-workspace memory access requires explicit federation

Multiple Workspaces

You can have many workspaces on one machine:

# List all registered workspaces
atlas workspace list

# Work with a specific workspace
atlas signal trigger my-signal --workspace workspace-id

Best Practices

1. One Purpose, One Workspace

Create separate workspaces for different purposes:

• customer-support/ - Customer service agents
• code-review/ - Code analysis agents
• data-pipeline/ - Data processing agents

2. Version Control

Commit your workspace.yml to git:

git add workspace.yml
git commit -m "Add AI agent configuration"

3. Environment Variables

Use environment variables for sensitive data:

agents:
  my-agent:
    config:
      api_key: "${MY_API_KEY}"

4. Modular Configuration

For complex workspaces, split configuration:

agents:
  analyzer: !include agents/analyzer.yml
  reporter: !include agents/reporter.yml

Next Steps

• Learn about Agents and Jobs
• Understand Signals
• Explore example workspaces