Manifests and stacks

Define an environment once and start it the same way every time. A stack is a versioned, published set of packages that your admin curates. You find them under Stacks in the web app. A manifest is your saved recipe on top of one stack version: the packages you added or removed, the credentials each one uses, and how your spaces behave. You pick a manifest every time you start a space or a run.

What you can do with it

• One environment for the whole team. The Platform team owns backend-dev: Claude Code, Node, the github package bound to the team’s GitHub credential, and web-app cloned on start. Every team member launches it and gets the same setup.
• Your own variation. Clone backend-dev, add the postgres package, and bind your own database credential. The team’s manifest stays as it was.
• Hand a setup to a colleague. Send a copy gives them an independent manifest of their own. Credential bindings are removed, so they bind their own credentials, and they see a review panel the first time they launch it.

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

How it fits

The manifest adds your changes, credentials, allow list and workspace to the stack version. At launch, Marshal resolves it and freezes the result on the space or run.

• A manifest holds: the stack version, your package changes and their settings, a credential binding for each package, the idle time before auto-stop, a default compute size, your own network allow list, workspace settings such as repositories to clone and a start script, whether your memory documents are included, and an owner.
• Several instances of one package. Database packages that support several instances can appear more than once in a manifest. Each extra instance has an alias you choose, such as staging or prod, and its own credential. The agent sees each one as a separate connection named after the package and the alias, such as clickhouse-prod, and its instructions name every alias. Instances share the package’s version and move with it when the package is upgraded. See Create a manifest.
• A manifest runs on its owner’s credentials, never on those of the person who launches it. A team manifest uses the team’s credentials. See Whose access a run uses.
• A deputy binds one manifest, and every run it starts uses it.

Clone big repositories fast

Each repository in the workspace can carry clone options. Set them in a stack or in a manifest, on the repository entry, next to its URL, directory and ref.

A shallow clone of a large repository starts a space in a fraction of the time and disk. Ref still works. With Depth, Single branch or Filter, a branch or tag is cloned directly and a full commit SHA (40 characters, or 64 in a SHA-256 repository) is fetched at the same depth. A short SHA cannot be fetched into a shallow clone, so use the full one.

Marshal checks the values when you save a manifest or publish a stack, so a typo is caught before a space starts: Depth must be a whole number from 1 to 1000, Filter one of the three forms above (with bytes from 1 to 1073741824), and a repository entry accepts only the fields in this table, plus its URL, directory and Ref. The options are a fixed list on purpose: you cannot pass free-form arguments to git clone.

Submodules

Marshal initialises the submodules your repository commits, up to 100 in total and 3 levels deep. Each one is fetched over https or ssh from the same host as the repository: the hostname must match (case aside), and the URL must carry no explicit port, no password and, for https, no user. A relative submodule URL is resolved against its repository first, and a relative URL that would leave the repository’s host is refused. Your Git credentials for that host go only to that host.

Marshal skips a submodule that breaks a rule: another host, another transport, a port or credentials in its URL, a custom update command, an unsafe path, a path that two entries share, or an entry that is not a committed submodule. If the repository itself was cloned from a URL that is not https or ssh, Marshal skips all of its submodules. The space still starts, and its start log shows a warning naming the path. The same warning appears when submodules nest deeper than 3 levels, when a repository lists more than 100, when its .gitmodules cannot be read, or when a submodule cannot be fetched.

The Git host must support partial clone for Filter to work. A Marshal release older than this feature ignores the options and clones in full, so roll the platform out before you rely on them.

What happens at launch

1. Marshal resolves the stack version plus your changes into a concrete setup.
2. It checks the setup against policy. A policy problem stops the launch with the list of what to fix.
3. It freezes the resolved setup on the new space.

A running space keeps its setup until it stops. When you resume a stopped space, it picks up the manifest’s current setup and takes its size’s current definition (see Resume and Compute sizes). Your workspace and disk stay as they are. Edit the manifest and new spaces use the change at once. Existing spaces use it the next time they resume. When a newer version of your manifest’s stack is published, the manifest editor offers Upgrade to that version. Choosing Upgrade to is how a manifest moves to another stack version, and saving other changes to the manifest never changes its version. After you upgrade, new spaces use it and existing spaces move to it when they resume. A manifest’s owner or an admin can hold a manifest on its stack version, or revert it to the previous one. See Keep packages up to date automatically.

You can launch a manifest when you own it, are on the team that owns it, it belongs to the organization, or it was shared with you for use. A personal manifest launches only for its owner.

Related

• Create a manifest and Install a package into a manifest.
• Build and publish a stack.
• Marketplace packages: what goes into a stack.
• Spaces: what a manifest becomes.