Space Setup Guide

Learn how to create and configure workspaces where your AI agents can read files, write code, and manage projects.

What You'll Learn
Prerequisites
Understanding Spaces
Creating a Space
Working with Files
Environment Variables
Workspace Configuration
Best Practices
Troubleshooting

What You'll Learn

By the end of this guide, you'll know how to:

✅ Create isolated workspaces for agents
✅ Upload and manage files
✅ Configure environment variables securely
✅ Set up project structure
✅ Control access and permissions
✅ Work with persistent storage

Time to complete: 15-20 minutes

Prerequisites

Before starting, ensure you have:

✅ A TeamDay account (Sign up guide)
✅ An organization (Org setup)
✅ At least one agent created (Agent guide)
✅ Personal Access Token (PAT guide)

Understanding Spaces

What Are Spaces?

Spaces are isolated file system environments where AI agents can:

Read and write files
Execute code and commands
Store persistent data
Work with Git repositories
Access environment variables

Think of a space as a virtual workspace for your agents—like a project folder on steroids.

Screenshot

Key Features

Isolation

Each space has its own file system
Agents can't access files from other spaces
Secure multi-tenancy

Persistence

Files survive across agent executions
Automatic backup to S3 storage
Version control with Git

Flexibility

Start from scratch (empty space)
Clone existing Git repository
Use starter templates

Collaboration

Share spaces with team members
Multiple agents can work in same space
Real-time file synchronization

Space Use Cases

Software Development

Space: "Backend API Project"
- Clone Git repository
- Agents review and write code
- Commit changes back to repo
- Run tests and build

Data Analysis

Space: "Q1 Sales Analysis"
- Upload CSV datasets
- Run Python analysis scripts
- Generate visualizations
- Store results and reports

Content Creation

Space: "Blog Content Pipeline"
- Draft articles in Markdown
- Iterate with agent feedback
- Store images and assets
- Publish final content

Automation Scripts

Space: "DevOps Utilities"
- Store automation scripts
- Configuration files
- Deployment manifests
- Agent executes tasks

Creating a Space

Method 1: Via UI (Recommended)

Step 1: Navigate to Spaces

Log in to TeamDay
Click "Spaces" in the sidebar
Click "+ New Space" button

Screenshot

Step 2: Configure Basic Settings

Space Name:

Descriptive and specific
1-100 characters
Examples:
- ✅ "Customer API Backend"
- ✅ "Marketing Website Content"
- ❌ "Space 1", "Test", "Workspace"

Description (Optional):

Brief overview of space purpose
Helps team members understand context
Example: "Backend API for customer management system built with Node.js and PostgreSQL"

Screenshot

Step 3: Choose Initialization Type

Option A: Empty Workspace

Best for: Starting a new project from scratch

What you get:

Empty directory
Git repository initialized
Default CLAUDE.md instructions file
Ready for agent work

Click "Create Empty Space"

Screenshot

Option B: Clone Git Repository

Best for: Working with existing codebases

Requirements:

Git repository URL (HTTPS or SSH)
Access credentials (for private repos)

Steps:

Select "Clone from Git"

Enter repository URL

https://github.com/username/repository.git

(Optional) Specify branch
- Default: main or master
- Example: develop, staging
Click "Clone Repository"

Screenshot

Option C: Use Starter Template

Best for: Quick project setup with best practices

Available templates:

Nuxt - Full-stack Vue framework
Next.js - React framework
Vue - Frontend framework
React - Frontend library
Express - Node.js backend
FastAPI - Python backend

Each template includes:

Project boilerplate
Dependencies configured
CLAUDE.md with project instructions
Best practice file structure

Select template and click "Create from Template"

Screenshot

Step 4: Set Visibility

Control who can access your space:

Private (Default)

Only you can access
Best for: Personal projects, experiments
Agent access: Only agents you assign

Organization

All organization members can access
Best for: Team collaboration
Agent access: All org agents available

Public

Anyone with link can view (read-only)
Execution requires org membership
Best for: Demos, open source, showcases

Screenshot

Step 5: Create Space

Click "Create Space"

Initialization process:

Creating file system
Initializing Git (if applicable)
Cloning repository / setting up template (if applicable)
Setting up S3 sync
Ready! ✅

Progress shown in UI. Usually takes 10-30 seconds.

Screenshot

Step 6: Access Your Space

Once ready, you'll see:

Files tab - Browse and manage files
Chat tab - Interact with agents in this space
Settings tab - Configure space options
History tab - Git commit history

Screenshot

Method 2: Via API

Create Empty Space:

curl -X POST "https://claude.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer API Backend",
    "description": "Backend API for customer management",
    "visibility": "organization",
    "type": "empty"
  }'

Clone Git Repository:

curl -X POST "https://claude.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Existing Project",
    "type": "git",
    "gitUrl": "https://github.com/username/repo.git",
    "gitBranch": "main"
  }'

Use Starter Template:

curl -X POST "https://claude.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Nuxt App",
    "type": "starterKit",
    "starterKit": "nuxt"
  }'

Response:

{
  "id": "s-abc123xyz",
  "name": "Customer API Backend",
  "description": "Backend API for customer management",
  "visibility": "organization",
  "status": "initializing",
  "organizationId": "org_xyz789",
  "createdAt": "2025-01-15T10:00:00Z",
  "s3Bucket": "teamday-workspaces",
  "s3Prefix": "org_xyz789/spaces/s-abc123xyz/"
}

Monitor initialization status:

curl -X GET "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Wait for status: "ready" before using the space.

Working with Files

File System Structure

Every space includes:

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

The CLAUDE.md File

Auto-generated instructions for agents working in this space:

# Project: Customer API Backend

Backend API for customer management system

## Context

This is a TeamDay workspace for: Backend development
Organization: Acme Corp
Space ID: s-abc123xyz
Created: 2025-01-15

## 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]

Customize CLAUDE.md to add project-specific instructions:

# Customer API Project

## Tech Stack
- Node.js 20+ with TypeScript
- Express.js for API framework
- PostgreSQL database
- JWT authentication

## Code Standards
- Use TypeScript strict mode
- Follow Airbnb style guide
- Max function length: 50 lines
- Write JSDoc comments for public functions

## Testing
Run tests before committing:
```bash
bun test

Common Commands

Development

bun run dev     # Start dev server (port 3000)
bun run build   # Build for production

Database

bun run migrate    # Run migrations
bun run seed       # Seed test data


![Screenshot](./images/space-setup/claude-md.png)

### Uploading Files

**Via UI:**

1. Open space → **Files** tab
2. Click **"Upload Files"** button
3. Select files from your computer
   - Max 20 files at once
   - Max 100MB per file
4. Choose destination directory (default: root)
5. Click **"Upload"**

Files appear immediately in the file browser.

![Screenshot](./images/space-setup/upload-files.png)

**Via CLI:**

```bash
# Upload single file
teamday spaces upload s-abc123xyz \
  --file data.csv \
  --dest /data/

# Upload multiple files
teamday spaces upload s-abc123xyz \
  --files config.json,schema.sql,README.md \
  --dest /

# Upload directory
teamday spaces upload s-abc123xyz \
  --directory ./src \
  --dest /src

Via API:

curl -X POST "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/files" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -F "[email protected]" \
  -F "path=/data/data.csv"

Reading Files

Via Agent:

Ask your agent to read files:

User: "Show me the contents of package.json"

Agent: [Uses filesystem tool to read file]

User: "What files are in the src/ directory?"

Agent: [Lists directory contents]

Screenshot

Via UI:

Navigate to Files tab
Click on any file
View contents in built-in editor

Via API:

curl -X GET "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/files?path=/package.json" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Writing Files

Via Agent:

Agents can create and modify files:

User: "Create a new file src/utils/helpers.ts with common utility functions"

Agent: [Creates file with content]

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

Agent: [Reads file, makes changes, writes back]

Screenshot

Via UI:

Click "New File" button
Enter file name and path
Write content in editor
Click "Save" (or Cmd/Ctrl+S)

Via API:

curl -X POST "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/files" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/src/utils/helpers.ts",
    "content": "export function formatDate(date: Date): string {\n  return date.toISOString();\n}"
  }'

Downloading Files

Via UI:

Navigate to Files tab
Right-click file → Download
Or select multiple → Download as ZIP

Via CLI:

# Download single file
teamday spaces download s-abc123xyz \
  --file src/app.ts \
  --output ./app.ts

# Download entire space
teamday spaces download s-abc123xyz \
  --all \
  --output backup.zip

Via API:

curl -X GET "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/files/download?path=/src/app.ts" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -o app.ts

Deleting Files

Via Agent:

User: "Delete the old test files in /tests/deprecated/"

Agent: [Removes files]

Via UI:

Select file(s) in file browser
Click Delete button (or press Delete key)
Confirm deletion

Via API:

curl -X DELETE "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/files?path=/old-file.txt" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Environment Variables

Store sensitive configuration securely.

Why Use Environment Variables?

Security:

API keys and secrets not in code
Encrypted at rest
Not exposed in Git history

Flexibility:

Different values per environment
Easy to update without code changes
Share spaces without sharing secrets

Best Practices:

Never commit credentials to Git
Use environment variables for all secrets
Rotate keys regularly

Setting Environment Variables

Via UI:

Open space → Settings tab
Click "Environment Variables"
Click "+ Add Variable"

Enter key and value:

Key: DATABASE_URL
Value: postgresql://user:pass@host:5432/db

Click "Save"

Variables are encrypted before storage.

Screenshot

Common Variables:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
REDIS_URL=redis://localhost:6379

# API Keys
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
STRIPE_SECRET_KEY=sk_test_xxx

# Application
NODE_ENV=development
PORT=3000
LOG_LEVEL=debug

# Authentication
JWT_SECRET=your-secret-key
SESSION_SECRET=another-secret

Via API:

curl -X POST "https://claude.teamday.ai/api/v1/secrets/set" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "s-abc123xyz",
    "key": "DATABASE_URL",
    "value": "postgresql://user:pass@host:5432/db"
  }'

Using Environment Variables

In Agent Code:

Agents can access variables when executing code:

# Python example
import os

database_url = os.environ.get('DATABASE_URL')
api_key = os.environ.get('ANTHROPIC_API_KEY')

// JavaScript example
const databaseUrl = process.env.DATABASE_URL;
const apiKey = process.env.ANTHROPIC_API_KEY;

In Configuration Files:

Use placeholder syntax:

{
  "database": "${DATABASE_URL}",
  "apiKey": "${ANTHROPIC_API_KEY}"
}

Viewing Variables

Via UI:

Settings → Environment Variables
See list of keys (values hidden)
Click "Reveal" to show value temporarily

Via API:

curl -X GET "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/environment" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Response (values encrypted):

{
  "variables": {
    "DATABASE_URL": "***encrypted***",
    "ANTHROPIC_API_KEY": "***encrypted***"
  }
}

Deleting Variables

Via UI:

Settings → Environment Variables
Find variable
Click Delete icon
Confirm

Via API:

curl -X DELETE "https://claude.teamday.ai/api/v1/secrets/DATABASE_URL?spaceId=s-abc123xyz" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"

Workspace Configuration

File System Limits

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

S3 Synchronization

All spaces automatically sync to S3 for durability:

How it works:

Agent modifies files locally
Changes detected by file watcher
Modified files uploaded to S3
Sync every 5 minutes + immediately on save

Benefits:

Automatic backup
Disaster recovery
Share across sessions
Access from multiple locations

Manual sync:

# Force upload to S3
teamday spaces sync s-abc123xyz --direction up

# Force download from S3
teamday spaces sync s-abc123xyz --direction down

Check sync status:

teamday spaces sync-status s-abc123xyz

Output:

{
  "spaceId": "s-abc123xyz",
  "lastSync": "2025-01-15T10:30:00Z",
  "pendingChanges": 0,
  "syncEnabled": true
}

Assigning Agents

Give specific agents access to a space:

Via UI:

Open space → Settings → Agents
Click "Assign Agent"
Select agent from dropdown
Click "Add"

Assigned agents:

Can read/write files
See space context
Receive instructions from CLAUDE.md

Screenshot

Via API:

curl -X POST "https://claude.teamday.ai/api/v1/spaces/s-abc123xyz/agents" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "char_def456"
  }'

Best Practices

1. Organize Your Files

Use standard project structure:

project-space/
├── CLAUDE.md          # Instructions
├── README.md          # Project docs
├── 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

2. Use .gitignore

Always ignore:

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
.next/

# Environment
.env
.env.local

# Logs
*.log
logs/

# OS
.DS_Store

3. Document in CLAUDE.md

Make it easy for agents:

# Quick Reference

## Start Development
```bash
bun install
bun run dev

Run Tests

bun test

Common Tasks

Adding API endpoint: Create file in src/api/
Database migration: Run bun run migrate
Deploy: Push to main branch (auto-deploys)


### 4. Secure Your Secrets

**Do:**
- ✅ Use environment variables for all secrets
- ✅ Add `.env` to `.gitignore`
- ✅ Rotate keys regularly
- ✅ Use different keys per environment

**Don't:**
- ❌ Commit secrets to Git
- ❌ Share secrets in chat messages
- ❌ Use production keys in development

### 5. Keep Spaces Focused

Create separate spaces for:

- **Development** - Active work
- **Staging** - Pre-production testing
- **Production** - Read-only reference
- **Experiments** - Try new ideas

### 6. Regular Backups

Even with S3 sync, maintain backups:

```bash
# Weekly backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
teamday spaces download s-abc123xyz \
  --all \
  --output "backups/project-$DATE.zip"

7. Monitor Space Size

Keep spaces under 1GB for best performance:

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

Large files to avoid:

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

8. Clean Up Regularly

Remove unused files:

User: "Delete unused files in /tmp and old branches"

Agent: [Cleans up workspace]

Troubleshooting

Space Stuck in "Initializing"

Problem: Status never reaches "ready"

Solutions:

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

# Cancel and retry
teamday spaces delete s-abc123xyz
teamday spaces create --name "My Space" --type empty

Files Not Syncing

Problem: Changes not appearing in S3

Solutions:

# Verify sync enabled
teamday spaces config s-abc123xyz --get SYNC_ENABLED

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

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

"Permission Denied" Errors

Problem: Agent can't access files

Check:

Agent assigned to space
Space visibility correct
Organization membership valid

teamday spaces info s-abc123xyz

Large Upload Fails

Problem: File upload times out

Solutions:

Split into smaller files (under 100MB each)
Use CLI instead of UI (more reliable)
Compress before upload (zip files)

# Upload via CLI
teamday spaces upload s-abc123xyz \
  --file large-dataset.csv.gz \
  --dest /data/

Next Steps

Now that you have a space set up:

1. Enable Git Integration

Connect to GitHub repositories
Guide: Git Integration

2. Work with Agents in Spaces

Execute agents with space context
Guide: Creating Your First Agent

3. Install MCP Plugins

Add tools for your agents
Guide: MCP Plugins

4. Set Up Automation

Schedule recurring tasks in spaces
Guide: Automation

Learning Resources

[Spaces API Reference - Complete API docs
**** - Advanced file management
**** - Secure your spaces

Happy workspace building! 🚀