Workspace

A workspace is the unit of a project in Sursakit. It holds every service the project runs, every session you're working in, plus the skills, automations, and tasks tied to it.

What lives in a workspace

• Services — containerized components (app, API, database, worker, …).
• Sessions — branch-like lines of work, each with its own runtime state.
• Skills — capabilities the Codex agent can use, both system-provided and workspace-defined.
• Automations — scheduled or manual runs that invoke the agent with a saved prompt.
• Tasks — work items assignable to humans or to Codex.
• Webhook integrations — connectors to GitHub, GitLab, Bitbucket, Linear, or Sentry that auto-create tasks.

Lifecycle

1. Create the workspace under an organization. Use Auto-create from a template or build it up service-by-service.
2. Add services — import from Git, Docker Hub, upload, or start empty.
3. Open a session — every workspace ships with a default main session. Spin up new sessions for parallel work.
4. Edit and run — services run on demand inside session-scoped runtimes.
5. Ship — commit through the version-control panel, open pull requests, merge.

API surface

Every workspace operation has a corresponding REST endpoint under /api/v1/workspace:

• POST /workspace — create.
• GET /workspace and GET /workspace/{id} — list and read.
• PUT /workspace/{id} — update.
• DELETE /workspace/{id} — delete.
• GET /workspace/{id}/default-session — fetch the default session id.

Runtime, service, filesystem, task, and version-control endpoints are session-scoped under /workspace/{session_id}/.... Workspace settings, skills, automations, members, and pull requests use the workspace id.

Caveats

• Duplicating a workspace is not yet supported as a single action. Workaround: create a new workspace from the same services, or upload the same folder into a new workspace.
• A workspace deletion removes its sessions and runtime state. Imported services and external Git remotes remain unaffected.