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

Using the workspace header

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

$
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:

$
GET /workspaces

Create a workspace

$
POST /workspaces
$
$
{
>
  "name": "My Team",
>
  "description": "Shared workspace for the engineering team"
>
}

The caller becomes the owner automatically.

Invite members

$
POST /workspaces/{workspace_id}/members
$
$
{
>
  "email": "colleague@yourcompany.com",
>
  "role": "member"
>
}

Valid roles: owner, admin, member, viewer.

Change a member’s role

$
PUT /workspaces/{workspace_id}/members/{user_id}
$
$
{
>
  "role": "admin"
>
}

Remove a member

$
DELETE /workspaces/{workspace_id}/members/{user_id}

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

SDK example

1
import { ModboxClient } from "modbox-sdk";
2
3
const modbox = new ModboxClient({ token: process.env.MODBOX_API_TOKEN });
4
5
// List all workspaces you belong to
6
const { workspaces } = await modbox.listWorkspaces();
7
8
// Get details of a specific workspace
9
const workspace = await modbox.getWorkspace(workspaces[0].id);
10
console.log(workspace.members); // → [{ user_id, role, ... }]
11
12
// Invite a teammate
13
await modbox.addWorkspaceMember(workspaces[0].id, {
14
  email: "colleague@yourcompany.com",
15
  role: "member",
16
});