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

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",
});