# Spaces & Workspaces

Spaces are project workspaces where AI agents do real work — with files, tools, skills, secrets, and Git integration.

# Spaces & Workspaces

A Space is a project workspace where agents do their work. Think of it as a sandboxed project directory with files, installed tools, skills, secrets, and optionally a Git repository.

Every conversation runs inside a Space. When an agent reads files, runs commands, or uses tools — it all happens within the Space's sandbox.

---

## What's Inside a Space

| Component | Description |
|-----------|-------------|
| **Files** | A sandboxed filesystem where agents can read, write, and edit files |
| **Skills** | Installed capabilities with enable/disable control via `skillRefs` |
| **MCPs** | Tool integrations with enable/disable control via `mcpRefs` (e.g., Google Analytics, Ahrefs) |
| **Agents** | AI agents assigned to this workspace |
| **Secrets** | Encrypted environment variables (API keys, tokens) |
| **Git** | Optional Git repository (clone, pull, commit) |
| **CLAUDE.md** | Persistent instructions loaded into every conversation |
| **Publishing** | Share the Space as a static website at `{slug}.apps.teamday.ai` |

---

## How Spaces Work with Agents

Agents are created at the **org level** and then **added to spaces**. A single agent can be in multiple spaces — like an employee who works across projects.

### The Agent + Space Union

When an agent chats in a space, it gets access to the **union** of resources from both levels:

| Source | Resources |
|--------|-----------|
| **Agent-level** | The agent's own skills, MCPs, subagents, system prompt, model |
| **Space-level** | The space's installed skills, MCPs, env vars/secrets |
| **Filesystem** | The space's files, `CLAUDE.md`, `.claude/` directory, Git repo |

This is additive — the agent brings its own equipment, and the space provides the workshop with all the tools on the wall. Nothing is either/or.

### Space Chat vs Org Chat

- **Space chat**: The agent gets the full union of its own resources plus the space's resources, files, and context.
- **Org-level chat**: The agent only has access to its own resources (skills, MCPs, subagents). No space filesystem, no space-level tools.

### Resource Management

Spaces manage their own resources independently of agents:

- **`skillRefs`** — Skills installed in the space, each with enable/disable toggle
- **`mcpRefs`** — MCP integrations installed in the space, each with enable/disable toggle

This means you can install tools at the space level that every agent in the space can use, without configuring each agent individually.

---

## Create a Space

### Via Web App

1. Click **+ New Space** from the dashboard
2. Enter a name and optional description
3. Choose the type:
   - **Empty** — blank workspace
   - **Git** — clone from a repository URL
4. Set visibility: `private`, `organization`, or `public`
5. Click **Create**

### Via CLI

```bash
# Empty space
teamday spaces create --name "Marketing Hub"

# Space from a Git repo
teamday spaces create --name "Backend API" --type git --git-url https://github.com/your-org/repo.git
```

### Via API

```bash
curl -X POST "https://cc.teamday.ai/api/v1/spaces" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Hub",
    "description": "Content creation and SEO workspace",
    "visibility": "organization"
  }'
```

**Response:**

```json
{
  "success": true,
  "space": {
    "id": "abc123",
    "name": "Marketing Hub",
    "visibility": "organization",
    "skillRefs": ["core:research-assistant", "core:data-analyst"],
    "mcpRefs": []
  }
}
```

New spaces automatically include core skills.

---

## Install Resources

Add skills, MCP integrations, and agents to your Space.

### Add Skills

```bash
teamday spaces add-skill <space-id> core:research-assistant core:data-analyst
```

Via API:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addSkills": ["core:research-assistant", "core:data-analyst"]}'
```

### Add MCPs

```bash
teamday spaces add-mcp <space-id> google-analytics ahrefs
```

Via API:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addMcps": ["mcp-id-1", "mcp-id-2"]}'
```

### Add Agents

```bash
teamday spaces add-agent <space-id> <agent-id>
```

When you add an agent to a Space, TeamDay automatically:
1. Writes the agent definition to `.claude/agents/{name}.md`
2. Installs the agent's skill dependencies
3. Installs the agent's subagent dependencies

Via API:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addAgents": ["agent-id"]}'
```

### Remove Resources

```bash
teamday spaces remove-skill <space-id> core:data-analyst
teamday spaces remove-mcp <space-id> ahrefs
teamday spaces remove-agent <space-id> <agent-id>
```

Via API:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"removeSkills": ["core:data-analyst"]}'
```

---

## Secrets

Secrets are encrypted environment variables available to agents at runtime. Use them for API keys, tokens, and other credentials.

### Store Secrets

```bash
teamday spaces set-secret <space-id> OPENAI_API_KEY=sk-abc123 SLACK_TOKEN=xoxb-456
```

Via API:

```bash
curl -X POST "https://cc.teamday.ai/api/v1/spaces/<space-id>/secrets" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": {
      "OPENAI_API_KEY": "sk-abc123",
      "SLACK_TOKEN": "xoxb-456"
    }
  }'
```

Secret names must be `UPPER_SNAKE_CASE`. Values are encrypted at rest.

### List Secrets

```bash
teamday spaces secrets <space-id>
```

Returns key names only — values are never exposed.

### Remove Secrets

```bash
teamday spaces remove-secret <space-id> OPENAI_API_KEY
```

Via API:

```bash
curl -X DELETE "https://cc.teamday.ai/api/v1/spaces/<space-id>/secrets" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["OPENAI_API_KEY"]}'
```

### How Agents Access Secrets

Secrets are injected as environment variables in the agent's sandbox. If an MCP or skill configuration references `${API_KEY}`, it's resolved from the Space's secrets.

In `.mcp.json`:
```json
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["tool.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
```

---

## Files and Filesystem

Each Space has a sandboxed filesystem at:

```
/sandbox/{orgId}/spaces/s-{spaceId}/
```

Agents use built-in tools to interact with files:

| Tool | Operation |
|------|-----------|
| `Read` | Read file contents |
| `Write` | Create or overwrite files |
| `Edit` | Make targeted string replacements |
| `Glob` | Find files by pattern |
| `Grep` | Search file contents |
| `Bash` | Run shell commands |

### Browse Files (CLI)

```bash
teamday spaces ls <space-id> /
teamday spaces ls <space-id> /src/
```

### CLAUDE.md

Place a `CLAUDE.md` file in the Space root to provide persistent instructions to all agents:

```markdown
# Project Context

This is a Node.js API project using Express and PostgreSQL.

## Coding Standards
- Use TypeScript strict mode
- Write tests for all new endpoints
- Follow REST conventions

## Important Files
- src/routes/ — API routes
- src/models/ — Database models
- .env.example — Required environment variables
```

`CLAUDE.md` is loaded automatically at the start of every conversation. Use it for project-specific context that doesn't belong in the agent's system prompt.

### Special Directories

| Path | Purpose |
|------|---------|
| `CLAUDE.md` | Persistent instructions for all agents |
| `.claude/agents/` | Subagent definitions (markdown files) |
| `.claude/skills/` | Skill definitions |
| `.mcp.json` | MCP server configuration |
| `.git/` | Git repository (if connected) |

---

## Git Integration

Connect a Space to a Git repository for version-controlled workspaces.

### Clone a Repo

Create a Space with a Git URL:

```bash
teamday spaces create --name "Backend" --type git --git-url https://github.com/org/repo.git
```

### Git Operations (CLI)

```bash
teamday spaces git <space-id> status
teamday spaces git <space-id> pull
```

### In-Chat Git

Agents can use Git through the Bash tool:

```bash
git status
git add .
git commit -m "Add feature X"
git push
```

The web app also provides a Git panel for viewing diffs, staging changes, and committing.

---

## Chat in a Space

Chatting in a space is different from org-level chat. In a space, the agent gets full access to the space's filesystem, installed skills, MCPs, and secrets — on top of its own agent-level resources.

### Via Web App

Open a Space and select an agent from the chat panel. The agent automatically has access to all the Space's resources.

### Via CLI

```bash
teamday spaces chat <space-id> --agent <agent-id>
```

### Via API

```bash
curl -X POST "https://cc.teamday.ai/api/v1/agents/<agent-id>/execute" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review the files in src/",
    "spaceId": "<space-id>"
  }'
```

---

## View Space Details

### Via CLI

```bash
teamday spaces get <space-id>
```

Shows the full profile including installed skills, MCPs, agents, and secret keys.

### Via API

```bash
curl "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN"
```

---

## Update a Space

Update metadata, cover image, or installed resources:

```bash
# Update name
teamday spaces get <space-id>  # not yet available via CLI update
```

Via API:

```bash
curl -X PATCH "https://cc.teamday.ai/api/v1/spaces/<space-id>" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Hub v2",
    "description": "Updated workspace",
    "instructions": "Focus on SEO content",
    "coverImage": "https://images.unsplash.com/photo-123"
  }'
```

### Disable Built-in Tools

Restrict which tools agents can use in this Space:

```json
{
  "disabledTools": ["Bash", "WebSearch"]
}
```

This prevents all agents in the Space from using the listed tools.

---

## Publish & Share a Space

You can publish a Space as a static website, making its files accessible at a public URL like `https://my-project.apps.teamday.ai`.

This is useful for sharing reports, dashboards, documentation, or any static content generated by agents.

### Publish via Web App

1. Open a Space and click the **Share** button
2. Enter a slug (e.g., `my-project`)
3. Optionally enable **Password protect** and set credentials
4. Click **Publish**

### Publish via CLI

```bash
# Publish without protection
teamday spaces share <space-id> my-project

# Publish with Basic Auth
teamday spaces share <space-id> my-project --user demo --pass secret123
```

The CLI verifies the site is live after publishing.

### Publish via API

```bash
curl -X POST "https://cc.teamday.ai/api/spaces/<space-id>/publish" \
  -H "Authorization: Bearer $TEAMDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-project",
    "username": "demo",
    "password": "secret123"
  }'
```

Username and password are optional. If provided, visitors must authenticate via HTTP Basic Auth.

### Unpublish

Remove the public URL:

```bash
teamday spaces unshare <space-id>
```

The Space's files are not affected — only the public URL is removed.

### Slug Rules

- 3-63 characters
- Lowercase letters, numbers, and hyphens only
- Cannot start or end with a hyphen
- Must be unique across all published spaces

---

## Delete a Space

```bash
teamday spaces delete <space-id>
```

Spaces are soft-deleted (archived), not permanently removed. Execution history is preserved.

---

## Next Steps

- [Space Setup](https://docs.teamday.ai/guides/space-setup) — Detailed setup workflows
- [Skills](https://docs.teamday.ai/guides/skills) — Build and install reusable capabilities
- [MCP Plugins](https://docs.teamday.ai/guides/mcp-plugins) — Connect external tools and integrations
- [Git Integration](https://docs.teamday.ai/guides/git-integration) — Repository management