Sessions and Cells

Every execution environment in Mudbase Cells is called a session. Sessions come in two flavors: ephemeral (no storage) and named (persistent volume).

Ephemeral sessions

An ephemeral session has no persistent storage. When the session ends - because its timeout expired, it was explicitly closed, or the server terminated it - the filesystem is gone. Multiple ephemeral sessions can run concurrently for the same organization with no volume conflicts.

Ephemeral sessions are the right default for one-shot or short-lived workloads: running a script, checking output, testing code. You create one, use it, and discard it.

Named cells (persistent volumes)

When you supply a cellName at session creation, the session is backed by a persistent workspace volume. The volume survives the session: when you create another session with the same cellName, it picks up where you left off.

Cell names must be 1 to 63 characters and contain only letters, digits, underscores, and hyphens ([a-zA-Z0-9_-]). They are unique per organization.

Warning
Each named cell can only be attached to one running session at a time. If a session with that cell name is already running, creating a second one with the same name will fail. Close the existing session first, or use a different cell name.

Concurrency

Multiple sessions can run at the same time for the same organization, subject to your plan's concurrent session limit. The key rule is:

  • Any number of ephemeral sessions can run concurrently (within the plan cap).
  • Named cells with different cell names can run concurrently.
  • Two sessions sharing the same cell name cannot run at the same time.

Session identity

Each session has a unique sessionId (a MongoDB ObjectId). This is what you pass to exec, file, service, and checkpoint endpoints. The sessionId changes every time you create a session, even for the same named cell.

Idempotent creation

Supply an externalId (a string up to 128 printable ASCII characters) to make session creation idempotent. If an active session already exists with thatexternalId for the same organization, the existing session is returned instead of creating a new one. This is useful for crash-recovery: after a process restart, call create again with the same externalId and you re-attach rather than spinning up a second session.