Safety and limits
What dry execution substitutes and what your code can still do.
Marbles executes local TypeScript with the authority of its host process. The CLI itself does not isolate arbitrary module code. Sandbox sessions offer separate execution constraints and tool permission profiles; those do not restrict top-level TypeScript or unrelated host operations. Environment variables, tokens, filesystem access, and network access remain available according to that process’s environment and permissions.
Dry execution
--dry-run substitutes operations owned by Marbles:
| Operation | Dry execution |
|---|---|
| Agent turn | Echo the prompt; structured output uses a schema-valid placeholder. |
| Git command through workspace helpers | Print the command. |
Context exec or sandbox command |
Print the command; return exit 0 with empty output. |
| Run, session, trigger, grant, and artifact writes | Keep them in memory for this process. |
| Parked run at quit | Cancel it. |
An empty successful command result cannot exercise failure handling or code that expects real command output.
Step bodies still execute ordinary code and can produce side effects. A raw
fetch, a file write, or a child process in a body happens for real. File
monitors still scan, HTTP monitors still use the network, and Git status can
still read the working tree. Worktree helpers still allocate a temporary
directory even though their Git commands are echoed. Clients and tools you
construct independently do not inherit these substitutions. Read the bodies
before running roll on a module you did not write.
Agents and authority
A working directory sets context, not a security boundary, and a sandbox mounts the step’s workspace read/write. A prompt asking an agent not to edit is an agent instruction, not an enforceable permission. Authentication and available host tools belong to the installed Claude Code or Codex CLI. Sandbox sessions use the Agents authorization contracts and Sandbox tools and constraints. They can enforce their configured tool approval profile; see Agent sessions. Review their configuration before granting an automation access to your work.
Schedule locks skip overlapping ticks for the same workspace and key. They do not coordinate every action or custom side effect across your machine.
Continuity has boundaries
State is saved to disk. Run history, trigger observations, sessions, and artifacts
survive separate invocations. A run parked on a question or a pause survives a quit, a crash, or a kill, and is
adopted by the next dashboard that can answer it. A run that was mid-body when
its process stopped is not resumed. Its last saved snapshot remains, but
newer progress may not have reached disk; status marks saved running
records orphaned. Cancellation stops what Marbles opened and cannot
undo side effects already made. Model judgments and conversation history do
not guarantee correctness.
Durability records and coordinates work. It does not grant permission for an external effect or make that effect happen exactly once. Retrying a step can issue another model request, command, or write; configure retries where repeating the work is safe.