Local execution and state
Connect the automation lifecycle to CLI processes and the stores they keep on disk.
The CLI hosts Marbles on your machine. Its process can execute one run and exit, or stay alive to launch runs, poll monitors, and answer questions.
A process and a run have different lifetimes. Starting the CLI loads your modules and runtime; launching an automation creates a run within that runtime. Keeping a dashboard open does not turn all its launches into one run.
From a module to a result
| Stage | What the CLI does | What your module does |
|---|---|---|
| Discover | Finds and imports automation modules. | Declares named work, resources, and triggers. |
| Bind | Prepares workspaces, providers, stores, and resource managers. | Supplies definitions that describe what it needs. |
| Launch | Starts a run with validated input. | Builds a workflow tree, or supplies a single step. |
| Execute | Runs the steps in dependency order. | Uses the execution context and returns results. |
| Retain | Saves run outcomes and updates the relevant stores. | Writes reports or artifacts that future work needs. |
This is the declaration-and-execution distinction from the earlier pages, now applied to a real process. Top-level module code executes during import, including for inspection commands. Step bodies execute when launched.
Choose the process lifetime
| Mode | Lifetime |
|---|---|
marbles roll <name-or-key> |
Dispatch one definition, schedule, or monitor and exit. Cannot answer a question. |
marbles |
Keep the dashboard active for schedules, monitors, launches, and answers. |
marbles run with piped input or output |
Keep schedules and monitors running with plain output. Cannot answer a question. |
Keep Marbles running to execute triggers on their cadence. roll executes
one target immediately; it does not keep a clock running. Both modes use the
same workspace state. Restart an open dashboard to load edited modules.
See the CLI reference for commands and controls.
Different stores remember different things
| State | What it answers |
|---|---|
| Run snapshot | Which steps finished, what they returned, and whether this run is waiting. |
| Agent session | Which messages belong to this conversation. |
| Artifact content | Which files and evidence a particular output version contains. |
| Trigger state | When a schedule finished or which observation a monitor last handled. |
Workflows, Agents, and Artifacts supply the underlying contracts. Marbles connects their records and provides local persistent stores by default. A transcript alone cannot tell the workflow which steps finished; a run snapshot alone does not contain every artifact’s file bytes.
Run and session state belongs to the canonical workspace path, under
~/.foundry/marbles/<workspace-id>/ by default. Artifact content lives
separately under ~/.foundry/artifacts/. Preserve both when moving or backing
up an automation. The state reference documents
the files and their ownership rules.
What a restart keeps
A new process reads the saved state. An answering dashboard can adopt a parked run when its definition remains available and its previous ownership has ended. A run interrupted while actively executing is not adopted. The durability guide explains the recovery boundary and why a fresh launch can repeat earlier work.
Under --dry-run, Marbles keeps its state in memory and substitutes managed
operations. Ordinary TypeScript and monitor I/O still execute. See
safety and limits for the precise boundary.
An embedding host provides its own package instances and persistent stores. A remote host uses the same process model with its own tools and credentials.
Next: Foundry primitives connects the concepts you have used to the libraries underneath Marbles.