#Ethereal Workspaces

Ethereal Workspaces run omp inside an isolated workspace instead of mutating the source checkout. The workspace is active for the whole agent session: every prompt, tool call, shell command, edit, test, and follow-up turn sees the workspace as the project root until the session exits.

They are useful for both one-shot prompts and full interactive sessions.

#Quick usage

# One-shot prompt
omp -p "fix failing tests" --ethereal --workspace-mode auto

# Full interactive session: the TUI session runs inside the workspace until you quit
omp --ethereal --workspace-mode auto

# Preserve the workspace for inspection after the session exits
omp --ethereal --workspace-mode worktree --preserve-workspace

# Export a patch when the session exits
omp --ethereal --workspace-mode auto --export-patch ./agent-output/fix.patch

#Workspace modes

The manifest records both the requested workspaceMode and the actual actualWorkspaceMode (copy, reflink-copy, or worktree).

#Session lifecycle

1. Resolve the source repo from the launch cwd.
2. Materialize the workspace according to --workspace-mode.
3. Copy only explicitly allowed env or secret files.
4. Write .ethereal/manifest.json.
5. Start the agent session with the workspace as cwd.
6. Keep all session turns and tools inside that workspace.
7. On session exit, export a patch if requested.
8. Clean the workspace by default, or preserve it when --preserve-workspace is set.

--ethereal does not mean "only isolate the first prompt." It means the active agent session is rooted in the Ethereal Workspace until the run ends.

#Secrets and env files

Secrets are never copied by default.

omp --ethereal --copy-env
omp --ethereal --env-file .env.local
omp --ethereal --copy-secret ~/.npmrc
omp --ethereal --secret-allowlist ./ethereal-secrets.allow --copy-secret ~/.npmrc

--copy-env copies common repo-root env files when present: .env, .env.local, .env.development, and .env.test.

Explicit files inside the repo keep their relative path. Explicit files outside the repo are copied into .ethereal/secrets/ and are redacted from the manifest.

#Patch export

omp --ethereal --workspace-mode auto --export-patch ./fix.patch

Patch export excludes .ethereal/, env files, secrets, dependency folders, caches, and build outputs.

For worktree mode, source dirty state is treated as the baseline. The exported patch contains changes made by the agent session, not pre-existing dirty source changes.

#Safety notes

• The source checkout contents are not mutated by Ethereal Workspace materialization.
• Reflinks are copy-on-write clones and are safe for this use.
• Hardlinks are intentionally not used: in-place writes through a hardlink can mutate the source checkout.
• worktree mode shares Git metadata/object storage with the source repository, but edits happen in the detached worktree path.
• Cleanup refuses to delete paths outside the configured workspace root or paths without an Ethereal manifest.

#Settings

Equivalent config shape:

{
  "workspace": {
    "enabled": true,
    "mode": "auto",
    "root": null,
    "preserve": false,
    "copyEnv": false,
    "envFiles": [],
    "secretFiles": [],
    "secretAllowlist": null,
    "exportPatch": null,
    "name": null
  }
}

CLI flags override config values for the current run.