Get Started

Workspaces

Organization context, personal space, workspace selection, and members.

A workspace is the organization boundary for shared Epismo data. If no workspace is selected, data is stored in personal space.

Workspace names use the same constraints as workspace subdomains: 3 to 30 characters, lowercase letters a-z, numbers 0-9, and hyphens. Reserved names are rejected.

Use a workspace when data belongs to an organization rather than one person: team projects, shared packs, workflow runs, member management, and billing. Keep personal experiments in personal space until they need team access.

Personal space

Personal space belongs to the current user. Use it for private experiments, drafts, and individual workflows that should not be shared with a team.

Personal space has no projects. To share private data with a group, switch to a workspace and use project scope.

Workspace context

The CLI resolves workspace context in this order:

  1. EPISMO_TOKEN embedded workspace.
  2. Saved default from epismo workspace use $WORKSPACE_ID.
  3. Personal space fallback.

The API can accept workspaceId on supported endpoints. MCP derives workspace context from the bearer token.

For automation, prefer an explicit workspace context: pass workspaceId to API calls, run epismo workspace use before CLI scripts, or issue a workspace-scoped token with epismo token create --workspace-id. That keeps credit usage and private data access predictable.

Projects inside a workspace

Workspace membership alone does not mean every member can see every private pack or track. Projects are the private sharing containers inside a workspace. Put packs and tracks in scope: { "type": "projects", "ids": [...] } when a specific group should collaborate on them. See Projects and Scopes.

Members

Workspace member roles are:

Role Use for
owner Workspace ownership and administration
admin Administrative operations
member Standard workspace access

Workspace membership determines which users can participate in workspace projects and appear in workspace user resources.

Workspace plan values are basic and pro. Workspace checkout returns a billing URL for completing or retrying payment.

When to use

  • Use personal space for private drafts and individual workflows.
  • Use a workspace when data, billing, or member management belongs to an organization.
  • Use projects inside the workspace to decide which members can see specific private packs and tracks.