Spaces and storage

Get an isolated environment for an agent, stop it when you are done, and pick up exactly where you left off. Your files live in your org’s own encrypted storage, separate from the compute, so a space can be stopped, moved and rebuilt while every file stays. For what a space is and its states, see Spaces.

Stop, resume, fork and archive are available when your administrator sets up space storage.

What you can do with it

• Stop at 6pm, resume at 9am. Stop your space at the end of the day and pay for no compute overnight. Resume it in the morning: your node_modules, your branch and your uncommitted diff are all there.
• Try a risky refactor in a fork. Fork a stopped space to get a second one with a copy of its workspace. Let the agent rewrite the module there. Keep the fork if it works and delete it if it does not. The original never changes.
• Work from your laptop. Mount the space’s shared folder (/home/agent/shared) on your machine with marshal spaces mount, or copy files in and out with push and pull, while the agent works inside.

See it end to end: A governed dev environment for every engineer.

How it works

What is saved

Marshal saves your whole home directory, /home/agent, except /home/agent/.marshal. That covers:

• your workspace at /home/agent/workspace, including node_modules, .git and uncommitted changes
• agent state, such as ~/.claude
• shell history, ~/.config and other dotfiles

Saving runs in the background about every 90 seconds while the space works, so your work is saved as you go. The saved copy is content-addressed, compressed and encrypted, and lives only in your org’s own bucket.

To keep paths out of the saved copy, add a .marshalignore file at /home/agent/workspace/.marshalignore. It uses .gitignore syntax and takes effect on the next save, with no restart.

A stop ends running processes and open terminals, and clears anything outside the saved set, such as /tmp, Docker layers and /home/agent/.marshal.

Resume

Resume starts a stopped space on fresh compute and restores the latest saved workspace. The CLI shows “Restoring workspace” progress. A compute size change you made while the space was running is applied on resume. So is an admin’s edit to the space’s size. See Edit a size.

Resume also brings the space up to date with its manifest. When the manifest has moved to a newer stack version or its settings changed, the space starts with the manifest’s current tools, images and network rules. Your workspace, disk, compute size and run history stay as they are. The space is set up for its owner, so the result is the same whoever resumes it.

If the update cannot be applied, for example because a tool version was removed or the owner can no longer launch the manifest, the space still starts on the setup it had before, unless that setup holds a blocked package version (see below). A banner on the space page says why. Fix the manifest, then stop and resume the space.

When the setup holds a package version that an admin blocked, the space does not start on the old setup. It starts on the manifest’s current setup, or the start is refused with a link to the manifest. See Security Center.

A space that runs an older manifest than the one it was made from shows a Runs an older manifest label on its card and on the space page. A running space says Restart to update, and a stopped one says Updates on next start.

Org owners and admins can turn the update off for the whole org with Refresh Spaces On Resume under Settings > Configuration, in the Spaces group. The default is always. With never, every space resumes on exactly the setup it was created with, and the Runs an older manifest label still shows. The exception is a space that holds a blocked package version: it is still refreshed onto its manifest, so a blocked version never starts. Run spaces are not updated.

Fork

Fork creates a new space from a copy of a stopped space’s workspace. You choose the manifest for the new space, so you can fork into a bigger size or a different toolset. The source space does not change.

Persistent disk

An admin can give a compute size a persistent disk instead of node-local storage. Then your whole /home/agent is one disk that belongs to the space. Resume attaches the same disk again with no restore step, so stopping and resuming keep your files even without space storage. If an admin changes the size to node-local storage, resume asks before it moves the workspace off the disk. The disk is freed when the space is archived or deleted. See Compute sizes.

Long-running spaces

Spaces are made to start when you need them and stop when you are done. A space that stays up for days holds its server, so the cluster cannot scale that server down, and routine cluster upgrades can restart it.

When a space has been running longer than your org’s threshold (2 days unless your administrator changes it), Marshal marks it with an amber Running 3d label on the space page, on its card on Spaces, and on its row under Running now on the home page. Hover the label to see how long the space has run and why to stop it. Stopping keeps your workspace, and resuming starts the clock again from zero. Run spaces are not marked.

Org owners and admins see every long-running space in one list from the admin dashboards. Owners and admins also get an alert for each one; see Alerts.

Names

If you do not name a space, Marshal makes a name from your first name, the agent and four characters of the space id, for example ofir-claude-bf4b.

Who can see a space

A space belongs to the person who created it. Other members cannot see or open it. Org owners and admins can see and manage every space from the admin dashboards.

In the web

A space in error shows Recover in place of Stop. Recover moves it to stopped, and you can then resume it or start a new space from a different manifest.

In the CLI

<id> can be a UUID, a slug, a name or a unique prefix. marshal space works as well as marshal spaces, and marshal stop, marshal resume and marshal fork work as top-level shortcuts.

The REASON column of marshal spaces list shows why a stopped space stopped, for example user, auto_stop or preempted.

Configure it

Idle time is measured from the last activity, which is agent network traffic or terminal use. Run spaces are never auto-stopped.

Keep a workspace after you delete a space

Deleting a space also deletes its saved workspace. To keep it, tick Retain workspace in the delete dialog. The volume gets a name and stays after the delete, and you can fork a new space from it later. The checkbox shows when the space has a saved volume.

Edge cases

• Fork needs a stopped space with a saved volume.
• A space that never had any activity is not auto-stopped.
• A volume that a space still uses cannot be deleted from Volumes. Stop or delete the space first, or retain the volume.
• If a space will not start, see Help with spaces.

Try it

marshal spaces new --manifest <your-manifest>

Make a change in the workspace, then run marshal spaces stop <id> and marshal spaces resume <id> --connect. Your change is still there.

Related

• Spaces
• Create a space
• Retention and archive
• Compute sizes
• Manifests and stacks
• CLI reference