Spaces & Workspaces

Learn how to work with isolated environments for agent execution in TeamDay.

What are Spaces?
Creating Spaces
Workspace Structure
File Operations
Git Integration
S3 Synchronization
Sharing Spaces
Best Practices

What are Spaces?

Spaces are isolated workspaces where agents can:

Read and write files
Execute code and commands
Commit changes to Git
Persist data across sessions
Collaborate with other agents

Each space provides:

Isolation - Separate file system per space
Persistence - Files survive across executions
S3 Sync - Automatic backup to cloud storage
Git Integration - Full version control
Access Control - Visibility and permissions
Agent Assignment - Dedicated agents per space

Use Cases:

Development Projects - Code repositories with Git
Data Analysis - Persistent datasets and scripts
Content Creation - Draft documents and iterate
Automation - Store scripts and configurations
Collaboration - Multiple agents working together

Creating Spaces

Via UI

Step 1: Navigate to Spaces page

Step 2: Click "+ New Space"

Step 3: Configure Space

Basic Settings:

Name (Required)
- 1-100 characters
- Descriptive and specific
- Example: "Customer API Project", "Marketing Content"
Description (Optional)
- What this space is for
- Key context for agents
- Example: "Backend API for customer management system"
Visibility
- private - Only you
- organization - All org members
- public - Anyone with link

Initialization Type:

Empty Workspace - Start fresh
- Creates empty directory
- Initializes Git repository
- Adds default CLAUDE.md instructions
Git Repository - Clone existing repo
- Enter Git URL (HTTPS or SSH)
- Optionally specify branch
- Example: https://github.com/user/repo.git
Starter Kit - Use template
- Choose from: Nuxt, Next.js, Vue, React
- Pre-configured with best practices
- Includes CLAUDE.md instructions

Step 4: Click "Create Space"

Initialization happens in background. Status updates:

pending → initializing → ready
Progress shown in UI
Usually takes 10-30 seconds

Step 5: Open Space

Once ready, click "Open" to view files or "Chat" to interact with agents in this space.

Via CLI

# Create empty space
teamday spaces create \
  --name "My Project" \
  --description "Backend API development" \
  --visibility organization \
  --type empty

# Clone from Git
teamday spaces create \
  --name "Existing Repo" \
  --type git \
  --git-url "https://github.com/user/repo.git" \
  --git-branch "main"

# Use starter kit
teamday spaces create \
  --name "New Nuxt App" \
  --type starterKit \
  --kit nuxt

Available kits: nuxt, nextjs, vue, react, express, fastify

Workspace Structure

Each space has an isolated filesystem:

/data/sandbox/{orgId}/spaces/s-{spaceId}/
├── CLAUDE.md                    # Agent instructions (auto-generated)
├── .git/                        # Git repository
├── .gitignore                   # Standard ignores
├── ...your files...

CLAUDE.md File

Auto-generated instructions for agents working in this space:

# Project: {Space Name}

{Description}

## Context

This is a TeamDay workspace for: {purpose}

Organization: {org-name}
Space ID: s-{id}
Created: {date}

## Guidelines

When working in this space:
- Follow existing code patterns
- Write clear commit messages
- Test before committing
- Document significant changes

## Files

[Agent: Use the `filesystem` tool to explore files]

## Commands

[Common commands for this project type]

You can edit CLAUDE.md to add:

Project-specific instructions
Coding standards
Architecture notes
Common tasks
Links to documentation

File System Limits

Total size: 10 GB per space
File count: Unlimited (reasonable use)
File size: 100 MB per file upload
Sync: Automatic every 5 minutes + on changes

File Operations

Agents can perform file operations using the Computer service.

Reading Files

View File:

Agent: Show me the contents of src/api/users.ts

[Agent uses filesystem tool to read file]

List Directory:

Agent: What files are in the src/ directory?

[Agent lists directory contents]

Search Files:

Agent: Find all files containing "TODO"

[Agent uses ripgrep tool]

Writing Files

Create New File:

Agent: Create a new file src/utils/helpers.ts with utility functions

[Agent writes file]

Edit Existing File:

Agent: Update src/api/users.ts to add input validation

[Agent makes targeted edits]

Replace Content:

Agent: Replace the getUserById function with this new implementation:
[code]

[Agent performs string replacement]

File Upload

Upload files from your local machine:

Via UI:

Open space
Click "Upload Files"
Select up to 20 files (100MB each)
Files appear in workspace root (or specified directory)

Via CLI:

teamday spaces upload s-space123 \
  --files data.csv,config.json \
  --dest /data/

File Download

Download workspace files:

Via UI:

Open space file browser
Right-click file → Download
Or select multiple → Download as ZIP

Via CLI:

# Download single file
teamday spaces download s-space123 --file src/app.ts

# Download entire workspace
teamday spaces download s-space123 --all --format zip

Git Integration

Every space is a Git repository.

Automatic Initialization

When creating a space:

git init
git config user.name "TeamDay Agent"
git config user.email "[email protected]"
git add CLAUDE.md
git commit -m "Initialize TeamDay workspace"

Agent Git Operations

Agents can use Git through commands:

Agent: Check git status

[Agent runs: git status]

Agent: Commit these changes with message "Add user validation"

[Agent runs: git add . && git commit -m "Add user validation"]

Agent: Show recent commit history

[Agent runs: git log --oneline -10]

Viewing Git History

Via UI:

Open space
Click "History" tab
View commits, branches, diffs

Via CLI:

teamday spaces git s-space123 log
teamday spaces git s-space123 diff HEAD~1
teamday spaces git s-space123 show abc123

Branching

Create and switch branches:

# Via agent
"Create a new branch called 'feature/add-auth'"

# Via CLI
teamday spaces git s-space123 checkout -b feature/add-auth

Remote Repositories

Connect to GitHub, GitLab, etc:

Step 1: Add remote

# Via agent
"Add Git remote: git remote add origin https://github.com/user/repo.git"

# Via CLI
teamday spaces git s-space123 remote add origin https://github.com/user/repo.git

Step 2: Push changes

# Via agent (requires GitHub PAT in space config)
"Push to origin main"

# Via CLI
teamday spaces git s-space123 push origin main

Authentication: For private repos, add credentials:

teamday spaces config s-space123 \
  --set GIT_USERNAME=user \
  --set GIT_TOKEN=ghp_xxxxx

S3 Synchronization

Workspaces automatically sync to S3 for durability and sharing.

How It Works

Local to S3 Sync:

Agent modifies files in workspace
Changes detected by file watcher
Modified files uploaded to S3
Sync happens every 5 minutes + immediately on file close

S3 to Local Sync (Lazy Loading):

Agent requests file that doesn't exist locally
Computer service checks S3
File downloaded if available
Subsequent reads are local (fast)

S3 Bucket Structure

s3://teamday-workspaces/
└── {orgId}/
    └── spaces/
        └── s-{spaceId}/
            ├── CLAUDE.md
            ├── src/
            │   └── app.ts
            └── ...

Manual Sync

Force immediate synchronization:

Upload to S3:

teamday spaces sync s-space123 --direction up

Download from S3:

teamday spaces sync s-space123 --direction down

Bi-directional:

teamday spaces sync s-space123

Sync Status

Check sync status:

teamday spaces sync-status s-space123

Output:

{
  "spaceId": "s-space123",
  "lastSync": "2025-01-15T10:30:00Z",
  "pendingChanges": 3,
  "syncEnabled": true,
  "s3Bucket": "teamday-workspaces",
  "s3Prefix": "org-xyz/spaces/s-space123/"
}

Disable Sync

For local-only workspaces (testing):

teamday spaces config s-space123 --set SYNC_ENABLED=false

Or via environment variable when running Computer service:

SYNC_VOLUMES_TO_S3=false bun run dev

Visibility Levels

Private:

Only space owner can access
Agents must be explicitly assigned

Organization:

All org members can access
Any org agent can be used

Public:

Anyone with link can view (read-only)
Execution requires org membership

Assigning Agents

Give specific agents access to a space:

Via UI:

Open space settings
Go to "Agents" tab
Click "Assign Agent"
Select agent(s) from list
Save

Via CLI:

teamday spaces assign s-space123 --agent char_abc123

Assigned agents:

Can read/write files in the space
See space context in executions
Receive space-specific instructions from CLAUDE.md

Collaborative Spaces

Multiple users/agents working together:

Setup:

Create organization-level space
Assign specialist agents (Backend, Frontend, QA)
Add project instructions to CLAUDE.md
Team members execute agents in the space

Example Workflow:

# PM creates space and tasks
teamday spaces create --name "API Project" --visibility org
teamday agents exec char_pm "Break down the API project into tasks" --space s-api

# Backend engineer agent works on implementation
teamday agents exec char_backend "Implement user endpoints" --space s-api

# QA agent reviews and tests
teamday agents exec char_qa "Test the user endpoints" --space s-api

# All work happens in same workspace

Access Control

Fine-grained permissions (UI only, via space settings):

Viewer - Read files only
Editor - Read/write files
Admin - Full control + settings

Best Practices

1. Use Descriptive Names

✅ Good:
- "Customer API Backend"
- "Marketing Website Content"
- "Q4 Data Analysis"

❌ Bad:
- "Project 1"
- "Test"
- "Stuff"

2. Add Clear Instructions

Edit CLAUDE.md with project context:

# Customer API Project

Backend API for customer management system.

## Tech Stack
- Node.js + Express
- PostgreSQL database
- JWT authentication

## Standards
- Follow RESTful conventions
- Write tests for all endpoints
- Use JSDoc for functions
- Max function length: 50 lines

## Common Tasks

### Run Tests
```bash
bun test

Start Dev Server

bun run dev

Database Migration

bun run migrate


### 3. Organize Files

Use standard project structure:

project-space/ ├── CLAUDE.md # Instructions ├── README.md # Project overview ├── package.json # Dependencies ├── src/ # Source code │ ├── api/ # API routes │ ├── services/ # Business logic │ ├── utils/ # Utilities │ └── types/ # TypeScript types ├── tests/ # Test files ├── docs/ # Documentation └── .github/ # CI/CD configs


### 4. Commit Frequently

Guide agents to make small, focused commits:

"After implementing each endpoint, commit with a clear message"


Rather than:

"Implement all endpoints then commit at the end"


### 5. Use Branches for Features

"Create a new branch 'feature/add-auth' for the authentication work"


Benefits:
- Safe experimentation
- Easy rollback
- Clear feature isolation

### 6. Clean Up Regularly

Remove unused files and branches:

```bash
# Via agent
"Delete unused files in /tmp and stale git branches"

# Via CLI
teamday spaces git s-space123 branch -d old-feature

7. Monitor Space Size

Keep spaces under 1GB for optimal performance:

# Check space size
teamday spaces info s-space123 | grep size

Large files to avoid:

node_modules (use .gitignore)
Build artifacts (.next, dist, build)
Large datasets (use external storage)
Binary files (images, videos)

8. Backup Important Work

While S3 sync provides backup, also:

Option 1: Push to Git Remote

teamday spaces git s-space123 push origin main

Option 2: Download Snapshots

teamday spaces download s-space123 --all --output backup-$(date +%Y%m%d).zip

Option 3: Automated Backups

#!/bin/bash
# daily-backup.sh

for space in $(teamday spaces list --format json | jq -r '.[].id'); do
  teamday spaces download $space \
    --all \
    --output "backups/${space}-$(date +%Y%m%d).zip"
done

9. Set Up .gitignore

Always ignore:

# .gitignore

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
.next/
out/

# Environment
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

10. Use Spaces for Isolation

Create separate spaces for:

Development - Active work
Staging - Pre-production testing
Production - Live deployments (read-only)
Experiments - Trying new approaches

Troubleshooting

Space Stuck in "Initializing"

Symptoms: Space status never reaches "ready"

Solutions:

# Check initialization logs
teamday spaces logs s-space123 --tail 50

# Cancel and recreate
teamday spaces delete s-space123
teamday spaces create --name "My Space" --type empty

Files Not Syncing to S3

Symptoms: Changes not appearing in S3

Check:

# Verify sync is enabled
teamday spaces config s-space123 --get SYNC_ENABLED

# Force sync
teamday spaces sync s-space123 --direction up

# Check sync logs
teamday spaces logs s-space123 --grep sync

Git Conflicts

Symptoms: Git operations fail with conflict errors

Solutions:

# Via agent
"Show git status and resolve conflicts in [file]"

# Or reset to last good state
teamday spaces git s-space123 reset --hard HEAD

Permission Denied Errors

Symptoms: Agent can't access space files

Check:

Verify agent is assigned to space
Check space visibility
Verify org membership

teamday spaces info s-space123 | grep -E 'visibility|assignedAgents'

Next Steps

Learn about executing agents in spaces
Explore Git workflows
See API reference for spaces
Set up automated backups