Remote execution

Run the CLI on another host and understand the current deployment boundary.

Marbles can run on another machine as a CLI process with its own project, dependencies, credentials, and persistent storage. The execution model is the same as local operation. There is no built-in deploy command, hosted control plane, remote dashboard connection, or distributed worker pool.

The roadmap describes the planned hosted service, server-side support, and event triggers.

One remote host

Prepare the target host with:

1. Bun and the standalone package.
2. The project and .foundry/marbles/ modules at a stable path.
3. The project’s dependencies and tools used by its steps.
4. Credentials available to that host. For agents, authenticate the installed CLI there; a login on your laptop is not a remote login.
5. Persistent directories for state and artifacts, writable by the account running Marbles.

After connecting to that host, run from its project root. These paths are examples; create and choose directories appropriate for the account:

cd /srv/my-project
marbles list
marbles roll inventory --state /srv/marbles-state --artifacts /srv/marbles-artifacts
marbles run --state /srv/marbles-state --artifacts /srv/marbles-artifacts </dev/null

inventory must be a definition in that project. Use an attended terminal and marbles for the dashboard if the work asks questions. Headless run starts triggers immediately and cannot answer workflow asks.

What deployment must supply

Your environment must keep the process alive, restart it when appropriate, capture logs, provision credentials, and update the project and package. Marbles does not provision those facilities. Reloading edited modules requires a process restart.

Process supervision and workflow durability serve different purposes. Restarting the CLI brings its loops back, but it does not resume an interrupted running step. A scheduler that launches roll again creates a new run. Account for earlier external effects before relaunching.

State is scoped to the canonical workspace path. Changing that path changes the workspace ID, even with the same --state directory. Artifacts live in a separate store. Preserve both stores when continuity matters, and stop active processes before moving state. The run snapshots from Workflows, Agents transcripts, and Artifacts content are distinct records; keeping only one store does not preserve the whole automation’s context.

Process locks contain local PIDs. They coordinate processes on one host; they are not distributed locks. Do not share one writable state store between independent machines as a worker-coordination mechanism.

Limits to plan around

• A parked run can be adopted by a later dashboard on the same setup. A run interrupted mid-body is not automatically resumed.
• An ephemeral host loses local history unless its storage is preserved.
• Host CLI authentication, sandbox guest lifetime, mounts, and networking must work on the target host. Containerizing the CLI does not itself provide a working MicroSandbox environment.
• A remote scheduler invoking roll must choose work that needs no interactive answer and account for its own retry policy.

This page describes the supported process and state model, not a tested deployment recipe for a particular cloud. Start by validating one complete local automation, then verify its actual tools and credentials on the target host. See state and recovery.