Marbles

Write local automations in TypeScript and run them with a standalone CLI.

Marbles is a standalone CLI for automations you write in TypeScript. Use it to inspect a project, run commands, connect steps into workflows, and repeat work on a schedule or when files change. Add a coding agent where the task needs judgment.

Marbles is alpha, starting at 0.0.1. Any 0.0.x release may introduce breaking changes. 0.1.0 will mark the first supported API baseline.

Your automations live in your project, under .foundry/marbles/. This is a complete automation:

import { step } from "@foundry.sh/marbles";

step("inventory").do(async ({ workspaces, log }) => {
  const files = await workspaces.current.files();
  log(`Found ${files.length} files`);
  return { files: files.length };
});

Run it with marbles roll inventory. The CLI prints the result and keeps the run history locally. Open marbles for the dashboard, or keep it running to execute schedules and monitors.

Workflows records the step results and provides optional retries and waiting points. Marbles binds commands, agent sessions, and resources to each run. See Durability for what it can retain and resume.

Start with one result

Install Marbles, then write your first automation. The first example needs no agent account, Git repository, or sandbox runtime.

Afterward, Using Marbles introduces the capabilities you can add: inputs, workflows, workspaces, agents, sandboxes, artifacts, human decisions, and triggers.

Understand how it works

Foundation starts with the Marbles model: definitions describe work, workflows connect it, and runs execute it. Contexts then connect that work to environments, agents, and outputs. Durability and triggers build on those ideas, followed by local state and the Foundry libraries underneath.

Build something useful

Use case	Outcome
Software Factory	Take an issue through implementation, review, delivery, and on-call follow-up.
Evaluations	Compare models, harnesses, and skills against recorded cases.
Design	Develop a brief into wireframes, a reviewed product, and ongoing design updates.
Productivity	Start the morning with GitHub, Slack, and document updates since you left work.

The reference covers commands, API details, project setup, and troubleshooting. Marbles primarily runs on your own machine; remote execution describes the setup and limits.

See what’s next

The roadmap follows the next additions: browser resources with reusable profiles, MCP access to your definitions, a hosted web application for people and agents, and deeper remote and event support.