Workspace

Teams & Multi-User Workspaces

A workspace is the top-level multi-tenant boundary in Open Astra. Every agent, session, memory entry, and tool run belongs to a workspace. Team workspaces allow multiple users to collaborate — sharing agents, running group sessions, and enforcing access controls through a role hierarchy.

Plans

PlanUse case
personalSingle-user workspace. No team members. Default for self-hosted single-user installs.
teamMulti-user workspace with role-based access control. Suitable for most teams.
enterpriseReserved for enterprise configurations. Identical to team in the current release.

The plan is set at creation time and can be updated via PUT /workspaces/:id/settings.

Creating a workspace

The creator is automatically added as the owner.

bash
# Create a team workspace
curl -X POST http://localhost:3000/workspaces \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Engineering", "plan": "team" }'

# Response
{
  "id": "ws_abc123",
  "name": "Acme Engineering",
  "ownerId": "uid_alice",
  "plan": "team",
  "createdAt": 1740621600000,
  "settings": {}
}

Roles

Every workspace member has one of four roles. Roles are stored in workspace_members and mapped to a capability hierarchy used by the RBAC middleware:

RoleCapability levelWhat they can do
ownerownerFull control: manage members, settings, restrictions, grants, and delete the workspace
admineditorManage agents, settings, members, restrictions, and grants; cannot delete the workspace
membertool_runnerRun agents and tools, send chat messages, read sessions
viewerviewerRead-only access to sessions and agent responses; cannot trigger agent runs

Managing members

Adding a member is idempotent — posting the same uid again updates their role.

bash
# Add a member (owner or admin only)
curl -X POST http://localhost:3000/workspaces/ws_abc123/members \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "uid": "uid_bob", "role": "member" }'

# Change a member's role — same endpoint, upserts on conflict
curl -X POST http://localhost:3000/workspaces/ws_abc123/members \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "uid": "uid_bob", "role": "admin" }'
bash
# Remove a member (owner or admin, or self-removal)
curl -X DELETE http://localhost:3000/workspaces/ws_abc123/members/uid_bob \
  -H "Authorization: Bearer ${JWT_TOKEN}"

# Note: the owner cannot remove themselves.
# Transfer ownership before leaving.
ℹMembers can remove themselves from a workspace. The owner cannot — transfer ownership (by promoting another member to owner and demoting yourself) before leaving.

Group sessions

By default each user has their own isolated session thread per agent. Setting surface = "group" on a chat request creates a shared session: every user who sends with the same surfaceId joins the same conversation and sees the same history.

javascript
// WebSocket — join a shared group session
ws.send(JSON.stringify({
  type: "message",
  agentId: "support-agent",
  message: "What's the status of ticket #4821?",
  surface: "group",
  surfaceId: "support-room-1"
}))

// All users who send with surface="group" + surfaceId="support-room-1"
// share the same session and see the same conversation history.

Group sessions are useful for shared support queues, team standups, or any scenario where multiple people need to interact with the same agent thread. The agent's responses are visible to all participants.

Workspace settings

Two settings fields are available via PUT /workspaces/:id/settings (owner or admin only):

FieldDescription
defaultAgentIdThe agent used when no agentId is specified in a chat request
customAgentConfigsPer-workspace overrides for agent config fields (merged over the base config at request time)
bash
# Set a default agent for the workspace
curl -X PUT http://localhost:3000/workspaces/ws_abc123/settings \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "defaultAgentId": "general-assistant" }'
  • Model Restrictions — limit which providers and models workspace agents may use
  • Agent Grants — share agents from this workspace with other workspaces