Spaces

A space is your agent’s own computer: a terminal, your repositories already cloned, and exactly the tools and credentials its manifest grants. Start one, stop it when you are done, and pick up later with every file where you left it.

What you can do with it

Try a risky refactor in a fork. Fork your space to get a new one with a copy of its workspace. Let the agent rewrite the module there. Keep the fork if it works, delete it if it does not.
Keep one space per repository. Stop each space at the end of the day. Resume it tomorrow, and your branch, your files and your home folder are all there.
Pair with the agent. Work in the terminal, start an agent inside the same space, and review its changes before you push.

See it end to end: A governed dev environment for every engineer and Run a fleet of agents in parallel.

How it fits

You start a space from a manifest. Marshal resolves the manifest, checks it against policy, and freezes the result on the space. A running space keeps that setup until it stops. When you resume it, Marshal applies the manifest’s current version, keeps your workspace and disk, and starts the space on the updated setup. See Resume.
The space can reach only the addresses its network policy allows.
Credentials come from the manifest’s bindings. You never paste a secret into a space. See Credentials and connections.
Every run gets its own fresh space too. A run space does not show in your space list. To pick up a run’s work, continue the run. To work in its environment, take it over.

Lifecycle

A space starts, works, and stops:

A space stops when you click Stop or when the cluster preempts it. A ready space also stops when it is idle long enough to auto-stop. A space with a run’s agent in it stops when the run ends. If creating or resuming fails, the space shows Error, and recovering it takes it to Stopping.

After a stop, you decide what happens next:

An archived space is also deleted when the retention window ends.

State	What it means
Requested, Provisioning	Marshal is creating the compute and the disk.
Bootstrapping	Marshal is setting up the workspace, repositories, credentials and tools.
Ready	The space is up. Connect and work. An interactive space stays Ready while you use it.
Running	A run’s agent is working in the space. Ready and Running both count as active.
Stopping, Stopped	The compute is removed and your saved workspace is kept. Resume, fork, archive or delete it.
Archived	Hidden from the main list and shown on the Archive page. Restore it any time before the retention window ends.
Error	Creating or resuming the space did not finish. Recover it to try again.

A stopped space shows why it stopped: Stopped manually, Stopped by policy, Auto-stopped (idle), Preempted (the cluster took the compute back), Stopped: unhealthy (the environment crashed), or Stopped for security (an admin stopped it because it held a blocked package version). In every case your saved state is kept.

What survives a stop

Stopping removes the compute. Running processes and open terminals end. Your home folder, including the workspace, is saved by the storage your administrator sets up, and comes back on resume. Stop, resume, fork and archive are available when your administrator sets up space storage.

Idle auto-stop and retention

Idle auto-stop. Each manifest sets an idle time. When your admin turns on auto-stop, a space with no activity for that long is stopped. A space that never had any activity is not stopped.
Your spaces stay until you act. Marshal never archives or deletes a stopped interactive space by itself. Only you, or an admin, can do that.
Run spaces clean up after themselves. A finished run’s space is archived automatically, and every archived space is deleted after the retention window your admin sets. See Retention and archive.

Spaces and storage: every setting, the CLI, and what is saved.
Create a space: your first space, step by step.
Compute sizes: give a space more CPU and memory.
Runs: hand the agent a task in its own space.