Create a space from a manifest

Get an isolated environment with a ready agent in a few clicks. Start a space when you want to work with the agent side by side: fix a bug together, try a refactor, or explore a new codebase. The manifest decides the agent, the tools, the credentials, and the network rules.

Before you start

Role: any member.
A manifest you are allowed to launch. If you have none, New Space shows Create a manifest. It opens the manifest editor, and when you create the manifest you land back on New Space with it picked. See Create a manifest.

Steps

In the left rail, click Spaces, then New Space. The rocket button at the bottom of the rail (Create a new space) does the same.
Under Manifest, click Choose a manifest… and pick one. If you came from a manifest’s Launch button, it is already picked.
Optional: enter a Space name. If you leave it empty, Marshal generates one.
Click Create Space. It turns on once you pick a manifest. If the manifest needs credentials you have not added yet, an amber box lists the tools that will be in the space but are not authenticated. You can still create the space.
Wait on the Starting space page while Marshal sets up the environment. You are sent to the space when it is ready.
On the space page, click Open Terminal, or copy the command in the Ready to connect card to attach from your own terminal.

If a credential is missing

You do not have to add every credential before you start. A space starts with the tools it has, and a tool without a credential returns a clear not_authenticated error that names the integration when the agent calls it. The tools that do have credentials work as usual.

On the space page, the status bar shows a badge such as “2 tools not authenticated”, and the Tools without credentials strip at the top of the main column lists each one on its own row, with the credential it needs:

State	What it means	What to do
Missing	The manifest names a credential that does not exist yet.	Click Add credential. After you add it the row says Available now and Restart to apply. Restart the space to use it.
Not bound	The manifest names no credential for this tool.	Click Open manifest, bind a credential, then start a new space.

Click the chevron to collapse the strip to one line that names the tools, or click Dismiss (the X) to hide it. If another tool loses its credential later, the strip shows again.

A running space never changes under you: a new credential applies the next time the space starts. A run does not restart, so a credential you add applies to the next run.

Your organization can choose to refuse these launches instead. See Credentials and connections.

From the CLI

Install and sign in first: Install the CLI.


marshal spaces new --manifest <name-or-id> --name my-space

--manifest is required. It takes a name, an ID, or a unique prefix.
--detach (or -d) creates the space and exits. It prints only the space name.
--mount mounts the space’s shared folder (/home/agent/shared) on your machine. It needs sshfs, and you cannot combine it with --detach.

Connect to an existing space later with marshal spaces connect <id>. Run one command in it with marshal spaces exec <id> -- <command>, and stop and resume it with marshal spaces stop <id> and marshal spaces resume <id>. Every space command is in the CLI reference.

What you should see

A progress card on the Starting space page, then the space in the Ready state.
In the Ready to connect card: “Your space is up and the agent is waiting.” and the command marshal spaces connect <slug>.
On the Spaces list, a card for the new space with the buttons Connect and Stop.
In the CLI, progress lines while the space provisions, then a connected terminal. With --detach, only the name.

Give your agent its first task. Ask it to fix an issue in your repository, watch it work in the terminal, and review every file it touched on the Changes tab.