First Workspace
A workspace is the X4 unit of multi-repo development. It records selected repos,
branch strategy, sandbox profile, and generated worktree paths under .x4/.
Bootstrap
From any repo that belongs to a configured repo set:
x4 workspace bootstrap \
--entry "$PWD" \
--install eager \
--sandbox-profile azure-remote
Useful options:
| Option | Meaning |
|---|---|
--repo-set <id> | Select a registry repo set when inference is ambiguous. |
--feature <slug> | Use a named feature branch instead of the default generated session branch. |
--install eager | Install dependencies during bootstrap. |
--install skip | Create the workspace without dependency installation. |
--git-auth app | Use GitHub App auth for bootstrap clones. |
--workspace-backend auto | Let X4 choose native or parallel workspace behavior. |
Inspect
x4 status
x4 workspace status
Status shows the selected repo set, repo paths, branches, dirty state, sandbox metadata, and available actions.
Work And Validate
x4 test --continue-on-error
x4 sandbox up --profile azure-remote
x4 preview serve --host <tailnet-host>
azure-remote is a metadata-only starter profile unless the registry adds
services. It validates workspace and env wiring, but it does not start a
frontend, API, database, worker, or dashboard. Use a service-backed sandbox
profile before expecting preview URLs to serve an application.
Commit And Submit
x4 workspace commit -m "Describe the repo-specific change"
x4 workflow submit-pr --title "Describe the feature" --execute --push
Use x4 workflow submit-pr for the full developer PR path. It can rename a
temporary x4/session/... branch, commit per repo, create draft PRs, run
validation, and optionally post evidence.
Cleanup
Always dry-run cleanup first:
x4 cleanup --dry-run
x4 cleanup --force
X4 refuses dirty attached repos unless forced.