> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# Workspaces

A **workspace** is a team namespace in Modbox. All sandboxes, images, and registries are scoped to a workspace. When you sign up, a default workspace is created for you automatically.

## Workspace roles

| Role       | Create sandboxes | Manage images | Manage members  | Delete workspace |
| ---------- | ---------------- | ------------- | --------------- | ---------------- |
| **owner**  | Yes              | Yes           | Yes             | Yes              |
| **admin**  | Yes              | Yes           | Yes (not owner) | No               |
| **member** | Yes              | No            | No              | No               |
| **viewer** | No               | No            | No              | No               |

## Using the workspace header

To scope API requests to a workspace, include the `X-Workspace-Id` header:

```bash
curl https://api.modbox.run/sandboxes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: your-workspace-uuid"
```

Find your workspace ID in the dashboard or via:

```bash
GET /workspaces
```

## Create a workspace

```bash
POST /workspaces

{
  "name": "My Team",
  "description": "Shared workspace for the engineering team"
}
```

The caller becomes the **owner** automatically.

## Invite members

```bash
POST /workspaces/{workspace_id}/members

{
  "email": "colleague@yourcompany.com",
  "role": "member"
}
```

Valid roles: `owner`, `admin`, `member`, `viewer`.

## Change a member's role

```bash
PUT /workspaces/{workspace_id}/members/{user_id}

{
  "role": "admin"
}
```

## Remove a member

```bash
DELETE /workspaces/{workspace_id}/members/{user_id}
```

Members can remove themselves. Owners and admins can remove anyone (except the owner).

## SDK example

```typescript
import { ModboxClient } from "modbox-sdk";

const modbox = new ModboxClient({ token: process.env.MODBOX_API_TOKEN });

// List all workspaces you belong to
const { workspaces } = await modbox.listWorkspaces();

// Get details of a specific workspace
const workspace = await modbox.getWorkspace(workspaces[0].id);
console.log(workspace.members); // → [{ user_id, role, ... }]

// Invite a teammate
await modbox.addWorkspaceMember(workspaces[0].id, {
  email: "colleague@yourcompany.com",
  role: "member",
});
```

Use separate workspaces for different environments (e.g. `production`, `staging`, `development`) to isolate resources and control access.