The Marbles model
Understand the relationship between an automation, its steps, and each run.
An automation describes work you want to repeat. In Marbles, you write that description in TypeScript and launch it with the CLI. Each launch creates a run: one execution of the work, with its own input, progress, and result.
Start here after the quickstart. Foundation builds from the shape of an automation to the resources it uses, then to what happens when it waits, fails, or runs again.
Start with a step and a run
A step defines one piece of work and its result. The quickstart’s inventory is one step:
import { step } from "@foundry.sh/marbles";
step("inventory").do(async ({ workspaces }) => {
const files = await workspaces.current.files();
return { files: files.length };
});Loading this module defines inventory. Running marbles roll inventory
executes its callback and records the result. Running the command again
creates another run; the definition stays the same, but the files and the
result may have changed.
The callback receives a context. Here, workspaces is the part of that
context that gives the step access to the project. Other properties let a
step run commands, open an agent conversation, or report an outcome.
Connect work with a workflow
A workflow connects steps through their inputs and results. For example, a code review can collect changed files, ask an agent to review them, and save the findings. Each stage has a result the next stage can use.
| Concept | What it describes | In a review automation |
|---|---|---|
| Step | One piece of work. | Collect changes, perform a review, or write a report. |
| Workflow | How steps depend on one another. | The review receives the collected changes; the report receives the findings. |
| Run | One execution of a step or workflow. | This review of this project’s current changes. |
A single step is already launchable. Add a workflow when there are stages you want to connect and inspect separately. Both use the Workflows runtime; an agent is optional work inside a step.
Give the work resources and a way to start
The authoring API has three groups:
| Group | API | Question it answers |
|---|---|---|
| Work | step, workflow |
What should happen, and which results does it need? |
| Resources | workspace, agent, sandbox, artifact, skills |
Where does the work happen, what can it use, and what does it produce? |
| Triggers | schedule, monitor |
When should a new run start? |
Named steps and workflows appear in marbles list and the dashboard’s
Marbles panel. Resource declarations support that work. Schedules and
monitors appear in the Triggers panel. A trigger chooses when to launch
work; it does not replace the step or workflow it launches.
Use @foundry.sh/marbles for these declarations. Marbles bundles the libraries
behind them, so the automation stays independent of the Foundry repository.
Keep the identities separate
A definition can be used by many runs. A session identifies one agent conversation and can continue across runs. An artifact identifies a named output; its version identifies the exact files written at one point.
These identities serve different readers. A workflow consumes step results, an agent continues a session, and a later run reads an artifact version. The following pages introduce each as it becomes useful.
Next: Definitions and instances explains what the objects in an automation represent before anything runs.