Workspaces & Git

One sandbox per project

A project gets one resident sandbox. Workspaces are directories inside it at /workspace/{slug}, and everyone on the team reads and writes the same files. Files survive across runs — a script that writes report.md today finds it still there tomorrow.

Slugs are permanent

A workspace’s slug is generated when the workspace is created and never changes — the slug is the physical directory name, so renaming a workspace would orphan its files. The first workspace (slug default) is where tasks run unless told otherwise.

Choosing a workspace

A meta-task binds its default workspace; a create_task call can override it per run:

tid = create_task(
    "indexer",
    params={"source": "/workspace/docs/notes.md"},
    workspace_slug="docs",   # run against the docs workspace instead
)

GitLab-integrated workspaces

Bind a GitLab repository to a workspace and tasks there switch to git mode: each run gets its own worktree on a task-{id} branch, and on success the branch is pushed and a merge request is opened automatically — the MR URL lands on the task record.

Disposable sandboxes

Heavy or risky runs can execute in a one-off sandbox instead of the project sandbox: a fresh environment with the same workspace layout, created for the run and deleted when it ends.

Custom environments

When a task needs dependencies beyond the preinstalled SDK, build a custom image from a Dockerfile in the project’s Images tab and bind it to the meta-task (or to a background service). The image replaces the base environment for those runs; the workspace layout stays the same.