Paths And State

X4 stores repo-owned configuration in the registry and per-workspace state under the entry repo's .x4/ directory.

The short rule:

• read .x4/context.md first when you are a human or agent;
• read .x4/workspace.yaml when you need current machine-readable state;
• read .x4/workspace.lock.yaml when you need latest observed repo SHAs, dirty flags, sandbox state, preview state, or test artifact pointers.

Generated .x4/ files are local workspace state. They are intentionally untracked. X4 adds .x4/ to local Git excludes instead of editing the repo's tracked .gitignore.

Source Paths

Path	Meaning
src/cli.ts	Root CLI source.
dist/cli.js	Built CLI binary target.
documentation/	Docusaurus docs site.
docs/	Existing specs and historical docs.
apps/mastra-orchestrator/	Mastra app source when the current checkout includes it; some X4 checkouts only contain the docs, mirror workflow, and integration contracts.
extensions/vscode-x4/	Cursor and VS Code adapter.
plugins/x4-codex/	Codex plugin.

Workspace Files

Bootstrap writes these files under the entry repo:

.x4/
  context.md
  commands.md
  agent-instructions.md
  workspace.yaml
  workspace.lock.yaml
  x4-workspace.code-workspace
  repos/<attached-repo>/

Path	Meaning
.x4/context.md	Human/agent summary generated from the workspace and registry. Lists repo paths, roles, branch, setup commands, test commands, sandbox profile, and common X4 commands.
.x4/commands.md	Generated command cheatsheet for workspace commands and per-repo tests.
.x4/agent-instructions.md	Short agent rules: read context first, use workspace metadata, avoid secrets, avoid public preview URLs.
.x4/workspace.yaml	Current machine-readable workspace state. Records repo set, registry path, selected branch, entry repo, attached repo paths, sandbox state, preview state, worker target, ports, and runtime env references.
.x4/workspace.lock.yaml	Latest observed state. Records repo HEAD SHAs, dirty flags, sandbox state, preview state, and latest test run pointer. Rewritten by status-changing commands.
.x4/x4-workspace.code-workspace	Cursor/VS Code multi-root workspace file. Open this file to load all repos together.
.x4/repos/<attached-repo>/	Attached repo worktrees/checkouts. The entry repo is the workspace root; non-entry repos live here.

context.md is deterministic, not AI-generated. It is rendered from workspace.yaml plus the registry when X4 writes workspace files.

Runtime Folders

These folders are created as commands run:

These paths are present in a checkout or deployment that includes the Mastra orchestrator app source.

Path	Meaning
.x4/sandbox/	Current local sandbox metadata, generated Docker Compose file, runtime env files, logs, artifacts, and service volumes.
.x4/sandbox/env/	Sanitized runtime dotenv files created from selected non-production env sources. Values are not printed in logs.
.x4/sandbox/logs/	Local or copied remote sandbox logs.
.x4/sandbox/volumes/	X4-owned service data and masked metadata volumes for containers.
.x4/sandboxes/<id>/	Per remote-sandbox job artifacts, including SSH stdout/stderr and the generated remote script.
.x4/preview/	Tailnet preview proxy files, route metadata, logs, and runtime process metadata.
.x4/ai/	AI prompt and response artifacts. Prompts should include repo metadata and env key names, not secret values.
.x4/artifacts/tests/<run-id>/	Test run summaries and per-repo logs when x4 test runs.
.x4/control-submissions/	Local records for control-plane submissions.
.x4/issues.yaml	Linked issue mappings when issue workflows are used.

Sandbox State

x4 sandbox up writes sandbox state into .x4/workspace.yaml and .x4/workspace.lock.yaml.

For local service sandboxes, .x4/sandbox/docker-compose.yaml is the generated Compose file and Docker containers are labeled with:

com.x4.workspace-id=<workspace id>
com.x4.repo-set=<repo set>

x4 sandbox status uses those labels to reconcile saved workspace state with the actual Docker runtime. If .x4/workspace.yaml says a service sandbox is running but Docker has no running X4-labeled containers for that workspace, X4 marks the sandbox and preview stopped before printing status. Service and preview URLs are hidden in the stopped status output so dead links are not shown as tester links.

For remote worker sandboxes, the local workspace records:

• remote worker id and SSH user;
• remote workspace path;
• remote artifact path;
• compose project name;
• local copied SSH logs under .x4/sandboxes/<id>/.

Cleanup Commands

Use the narrowest cleanup command that matches the job:

Command	Scope
x4 sandbox down	Stop the current workspace sandbox but keep state.
x4 sandbox destroy --force --prune-artifacts	Destroy the current workspace sandbox and remove generated sandbox files.
x4 sandbox clear --all --dry-run	List X4-labeled sandbox resources on the current Docker host.
x4 sandbox clear --all --force	Remove discovered X4-labeled sandbox containers, Compose networks, Compose volumes, and X4 preview proxy processes on the current Docker host.
x4 sandbox clear --target <worker> --all --dry-run	List X4-labeled sandbox resources on a Docker-capable worker.
x4 sandbox clear --target <worker> --all --force	Clear X4-labeled sandbox resources on a Docker-capable worker.
x4 cleanup --dry-run	Show generated attached worktrees, sandbox state, preview state, and artifacts that would be cleaned for the workspace.
x4 cleanup --force --prune-artifacts	Remove generated attached worktrees and generated X4 artifacts for the workspace.

sandbox clear is host-level cleanup. It is intentionally guarded by --all and --force, and it only targets resources with X4 labels or X4 preview proxy process paths. Use --repo-set <id> or --workspace-id <id> to narrow it.

What Agents Should Read

When an agent opens a workspace:

1. Read .x4/context.md.
2. Read .x4/agent-instructions.md.
3. Use .x4/workspace.yaml for current repo paths and sandbox/preview state.
4. Use .x4/workspace.lock.yaml when reporting exact repo SHAs or dirty state.
5. Do not commit .x4/ files unless a maintainer explicitly asks for a generated artifact.