Compute sizes

Give each space the CPU, memory and disk its job needs, and grow a running space without a restart. A compute class is a named size. It sets what a space is guaranteed, and how far it may burst above that.

What you can do with it

• Match the size to the repo. Put your docs site on Small and your monorepo on Large. Each manifest carries its own size, so every space and run from it starts right.
• Rescue a build that hits its memory limit. Your build is close to its memory limit? Press Upgrade on the Resources tab and the space grows live, with no restart and no lost state.
• Keep costs in line. An admin limits which sizes your org and each stack may use, so nobody starts a 4x Large for a lint job.

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

The built-in sizes

Every org starts with seven sizes. Each is burstable: the space is guaranteed its request and may use more, up to its limit.

Medium is the built-in default. Each org gets its own copy of every built-in size, and an admin can edit them or add custom sizes.

Pick a size

If a run runs out of memory, its page says Out of memory. Move the manifest up one size. For a space you are working in, resize it live.

How it works

Requests and limits

A size’s disk figure is what the space reserves on its node, not what it has used. The Resources tab shows the used amount.

For a burstable size, limits come from requests: the CPU limit is 4 times the request, memory 1.5 times, and disk 2 times. An admin can set an explicit limit instead, as long as it is at least the request. A guaranteed size has limits equal to its requests.

At the limit:

• CPU: the space slows down (it is throttled).
• Memory: the process is stopped for running out of memory, and the audit log records space.container.oom_killed.

How a space gets its size

Marshal uses the first of these that is set:

1. The compute class sent with the request.
2. The compute class on the manifest.
3. The stack’s default class.
4. The org’s default class.
5. The built-in default, Medium.

To change the size for new spaces and runs, pick a Compute class in the manifest editor. It offers the sizes your org and stack allow.

For a deputy, set Default compute class on the deputy, or pick Compute class for this run in the launch dialog.

Choosing a size from the CLI

Pass the size name to marshal run --compute-class:

marshal run --manifest web-app --task "Run the full test suite" --compute-class large

The name is not case-sensitive. If it matches no size you can use, Marshal lists the sizes that are available. The class id works too, if you have it.

For a size you use often, set it on the manifest instead. Every run from that manifest then gets it with no flag.

Disk: node-local or persistent

Each size has a Storage mode:

• Ephemeral (the default): the home directory is node-local. Your files are saved to your org’s space storage as you work and when you stop. See Spaces and storage.
• Persistent disk: the whole home directory is one disk that stays with the space across stop and resume. Its size is the size’s reserved disk. The space also reserves 16 GiB of the node’s own disk for /tmp, container layers and logs. An admin changes that with Network Disk Space Node Reservation (GiB) in Settings > Configuration, Spaces group.

A disk change applies when you next resume the space.

Existing persistent disks keep the storage class they were created with. A change of storage class on a size applies to the disks the size creates from then on. A running space takes a storage change after you stop and resume it.

Resize a running space

Your build is hitting its memory limit? Open the space, go to the Resources tab and press Upgrade. The space grows live, with no restart. Available when your administrator enables live resize.

The Resources tab shows CPU, memory and disk for each container, with warning colors at 70 percent and error colors at 90 percent. Above the bars is the size control:

• Upgrade to the ceiling. When the size has a ceiling, one press raises the limits to it. The button reads Upgrade to <cpu> CPU / <memory>: live, no restart. At the ceiling it reads “At this class’s ceiling”.
• Change capacity… When the size has no ceiling, a dialog offers steps. CPU and memory change together.

A change applies in one of two ways:

• Live. The limits change on the running space with no restart. A live resize changes limits, never requests. Moving to another size is live when both sizes are burstable and have the same disk.
• At the next resume. Any other change, including any disk change, is saved and applied when you next resume. One saved change can wait at a time.

Below the bars, Recent resource events lists the space’s out-of-memory stops and resizes from the last 30 days, newest first, so a bar that jumped always has its reason next to it. The tab’s badge counts the out-of-memory stops.

Runs show the same Resources tab while they are live.

Configure it

Sizes are under Settings > Compute. Any member can read the sizes and the org policy. Org owners and admins create, edit and delete sizes, set the org default, and limit which sizes are allowed.

The built-in sizes, the org default and the last remaining size cannot be deleted.

Set storage on many sizes at once

Moving every size to persistent disk, or making gp3 the standard, takes one action. Owners and admins open Settings > Compute, choose Set storage on classes, and pick:

• Storage: Ephemeral or Persistent disk.
• Storage class: for a persistent disk, the cluster’s storage class. Leave it unset to use the org’s default storage class; when the org has none, choose one.
• Which sizes: all of your org’s sizes, or a selection.

Choose Preview first: nothing is saved until you choose Apply, and changing any choice clears the preview. For each size you see the storage and storage class it has now and the ones it would get. Built-in sizes are shared by every org, so they are skipped and marked as such. Your org’s own copy of a standard size is yours and is changed. A size that already has the requested storage is shown as unchanged.

The preview also tells you what happens to the spaces on each size, so you know the effect before you apply it:

• New persistent disk. Spaces on node-local storage that get a persistent disk when they next resume.
• Keep their disk and storage class. Spaces that already have a persistent disk and carry on with it on its existing storage class.
• Asked to choose. Spaces whose persistent disk would go away. On their next resume they choose between the new size and the one they have.

A space that has a move to another size waiting is counted under the size it is moving to. The spaces of a disabled size are not counted.

Apply changes every selected size together. If one size cannot take the change, nothing is saved and the preview shows why. Only the storage and storage class change; every other setting on the size stays as it is. Each changed size appears in the audit log as a compute class update, and the bulk action is recorded as one event.

When the change would move sizes from persistent disk to Ephemeral and spaces have a persistent disk on them, tick Confirm ephemeral under the preview to apply it.

An org owner or admin can run the same change from a connected assistant, up to 500 sizes at a time. See Connect an AI agent (MCP). It previews first; applying asks the person to confirm.

Default storage class

Set a Default storage class in Org policy. A new persistent size that names no storage class takes it, and so does a bulk change to Persistent disk that names none. The class form for a new persistent size comes with it filled in.

The default is copied when a size is saved. Changing it later does not change the sizes you already have. Clear it to go back to naming the storage class on each size.

Retire a size that is in use

Delete a size that stacks, manifests or deputies still use and Marshal shows how many of each. Pick another size under Move to and choose Move and delete. The stacks, manifests and deputies that used the old size switch to the new one in the same step, and the old size is gone. If the delete cannot finish, nothing moves.

If the org’s allowed sizes list holds only the size you are deleting, the new size takes its place in the list. A size nothing uses cannot be deleted while it is the only entry of that list: allow another size in the org policy first.

Spaces on the deleted size keep the size they have. To move one, change its size on the Resources tab.

See what uses a size

Before you change a size, see who depends on it. Owners and admins get a Used by column in the table, such as 3 manifests · 12 spaces. A size that nothing uses reads Not used.

Select the counts, or press Usage on the row, to open a list of every manifest and space on that size. Each name links to its page: a manifest opens in the editor, a space opens its page. Spaces show their state, and each entry shows its owner. A manifest you cannot open, such as another member’s personal one, is listed with its owner and no link.

• Manifests count when the manifest itself names the size. A manifest that follows its stack or the org default is not counted.
• Spaces count by the size they run on now, including stopped ones. If you resized a space, it counts under the new size. Deleted and archived spaces are not counted.
• Long lists show the newest 50 of each, with the exact total above and and N more below. The spaces list has Load more, which adds the next 50.

Edit a size

Change a size in Settings > Compute and every space on it picks up the new values the next time it is resumed. Stop and start a space, and it comes back with the size as it is now: CPU, memory, disk and storage. A space that already matches its size changes nothing, and a running space is never restarted for you.

A space that is behind its size shows Size out of date with its class on its Resources tab, with the values that differ. Admins see it in Settings > Compute: the size’s row shows N out of date next to its usage counts. In the size’s Usage list each such space is tagged with what differs, and the Out of date only checkbox, shown when at least one space is behind, lists just those. Load more adds the next 50.

A size change that moves a space from a persistent disk to node-local storage asks you first, because the persistent disk is not kept. The Resources tab says the next resume will ask. Starting that space in the web app shows the choice:

• Resume on the new size applies the whole change. The workspace moves off its persistent disk, and the space starts with its workspace restored from the space’s backup, or empty when space storage is not set up.
• Resume as it is keeps the space’s current size and its persistent disk. The space stays marked out of date, and asks again the next time it starts.
• Cancel leaves the space stopped.

Start from the CLI or from an agent and you get a message that says the same; finish the start in the web app.

A change from node-local storage to a persistent disk, and every other change, applies on start without a question. A space whose size has been deleted or disabled keeps the size it has.

A live resize is separate: it lasts for as long as the space is running, and the space does not show as out of date because of it. When you resume the space, it takes its size’s limits again.

Raising a size’s requests can make the space too big for the node it needs. Check Servers in the admin dashboards after you raise a size that many spaces use.

Edge cases

• A guaranteed size keeps its exact size and cannot grow live. Use a burstable size to resize.
• A request for a size your org or stack does not allow is refused when the space starts.
• Persistent disk is freed when the space is archived or deleted, not when it stops.

If a resize is refused, see Help with spaces.

Try it

Open a running space, select the Resources tab, and look at the size control above the bars.

Related

• Spaces and storage
• Change a space’s size
• Sizing & Capacity Planning
• Manifests and stacks
• Roles and permissions