Skip to main content

Execution Workspaces

An execution workspace is an isolated copy of a project's code — a git worktree with its own branch, path, and optional runtime — that SLAW creates for an agent to work in. Each issue run resolves a workspace so the agent always has a clean, identified code location.

Prerequisites

Services and jobs​

Each workspace can define two kinds of runtime commands:

KindBehaviour
ServiceA long-running supervised command (e.g. a dev server) that you start and stop manually
JobA one-shot command that runs once and exits (e.g. a build or database migration)

SLAW does not start or stop runtime commands automatically when an issue runs or when the server restarts. You control them from the workspace UI.

How workspace runtime config is inherited​

Project workspaces define the default set of commands available to agents.

  • The project workspace defines which services and jobs exist and how to run them.
  • Each execution workspace inherits that config by default but can override it with workspace-specific settings.
  • Any running service process is specific to its execution workspace — not shared between workspaces.

Changing project-level config does not affect services already running in an execution workspace until you restart them.

Start and stop runtime services​

Open an execution workspace in the SLAW UI, then:

  • Services tab — start or stop a long-running service.
  • Jobs tab — run a one-shot command on demand.

Both project workspaces and execution workspaces have these controls.

Workspace modes for issue runs​

When an issue runs, you choose how it resolves a workspace:

ModeWhen to use
New isolated workspaceThe issue needs a clean branch and runtime separate from other work. SLAW creates a new worktree.
Reuse existing workspaceContinue work on an established branch with running services already in place.
Shared workspaceMultiple issues collaborate on the same branch and running runtime. SLAW assigns them to the same workspace.

Multiple issues can legitimately share one workspace when they are working on the same change together.

How code persists between runs​

Code state moves between heartbeat runs through the local execution workspace — not through a git remote.

  1. At the start of each run, SLAW bundles the local worktree to the remote run directory.
  2. At the end of the run, new commits are written back into the local worktree directly.
  3. Agents must not git push or assume a remote exists.

If the write-back step fails, SLAW records workspace_finalize=failed on the execution workspace. Dependent issue wakes are gated until the next successful finalization.

Heartbeat workspace resolution​

Each heartbeat run follows this sequence:

  1. SLAW resolves a base workspace for the run.
  2. SLAW realizes the effective execution workspace — creating or reusing a worktree as needed.
  3. SLAW persists workspace metadata: paths, refs, and provisioning settings.
  4. SLAW passes the resolved code workspace to the agent run.

Runtime services remain under manual UI control throughout. SLAW does not auto-start or auto-stop services as part of this flow.

Archive a workspace​

Execution workspaces are durable until you archive them. Archiving:

  • Stops all running services in that workspace.
  • Cleans up workspace artifacts where safe to do so.

Workspaces that point at the project primary checkout are treated conservatively during cleanup — isolated worktrees are cleaned up more aggressively.

To archive, open the execution workspace in the SLAW UI and choose Archive.

Next steps​