CapsuleProcess

A run of a capsule: a live Linux sandbox you send commands to, with what it mounted, created and installed and every command’s result.

Kind: an object, used in responses.

Fields

Every field is present in a response; empty ones are null.

Field	Type	Description
`capsule`	`VersionReference`	The capsule and the version of it this run uses.
`dateStarted`	`datetime \| null`	When the run started, in UTC. Null until a worker picks it up.
`dateEnded`	`datetime \| null`	When the run ended, in UTC. Null while it is still going.
`status`	`CapsuleProcessStatus`	Where the run is in its life.
`failureDetails`	`string \| null`	Why the run failed, when its status is `Error`. Null otherwise.
`virtualFileSystemMounts`	`CapsuleVirtualFileSystemMount[]`	The virtual file systems mounted in the run, each at `/mnt/<mountName>`.
`secretMounts`	`CapsuleSecretMount[]`	The secrets mounted in the run, each as the file `/mnt/secrets/<mountName>`.
`commands`	`CapsuleProcessCommand[]`	Every command and operation sent to the run, in the order they were queued, with their status and output.
`hostname`	`string \| null`	Identifies the worker that ran this run, for diagnostics. Null until a worker picks it up.
`createdUsers`	`string[]`	The Linux users created in the run so far: the capsule’s own users and any added while it runs.
`installedPackages`	`string[]`	The Debian packages installed in the run so far: the capsule’s own packages and any added while it runs.
`defaultUser`	`string`	The user commands run as when they don’t name one: always `maitento`, never `root`.
`triggeredByAutomatedActionId`	`uuid \| null`	The automation that started this run (by its schedule, a message trigger or a manual trigger). Null when the run was started any other way.
`triggeredByAutomatedActionName`	`string \| null`	The automation’s name when it started this run (a snapshot). Null exactly when `triggeredByAutomatedActionId` is.
`retentionLeaseActive`	`boolean \| null`	True while a retention lease keeps this run: its own, or one inherited from a retained run that started it. A retained run is never deleted when the tenant’s retention period ends. Null or false: not retained.
`retentionLeaseAppliedAtUtc`	`datetime \| null`	When the lease was taken, in UTC. For an inherited lease, when the ancestor’s lease was taken.
`retentionLeaseAppliedByUserId`	`uuid \| null`	The id of the user who took the lease.
`retentionLeaseAppliedByUserName`	`string \| null`	The name of the user who took the lease, as it was when they took it.
`retentionLeaseNote`	`string \| null`	Why it is retained, as the person who retained it wrote it (optional, at most 500 characters).
`retentionLeaseInheritedFromProcessId`	`uuid \| null`	Null when the lease is this run’s own. Otherwise the id of the ancestor run whose lease keeps this one; releasing that run’s lease releases this one too.
`parentProcessId`	`uuid \| null`	The run that started this one: an app that called `CapsuleStart`. Null for a run started directly (through the API or an automation), or when it isn’t known.
`parentProcessType`	`ProcessType\| null`	What kind of run `parentProcessId` is. Null exactly when that is null.
`rootProcessId`	`uuid \| null`	The run at the top of this run’s tree, shared by every run in it, so you can group them with one comparison. Null for a capsule run started directly, which starts no other runs.
`dateRunnerPing`	`datetime \| null`	When the worker running this run last reported that it is still alive, in UTC. Null before it starts.
`waitingForLaneSinceUtc`	`datetime \| null`	When the run started waiting for a lane, in UTC; null when it isn’t waiting. A waiting run is in status New, and `GET /processes/{type}/{id}/lane` says why it waits. Set by Maitento.
`userCreatedById`	`uuid`	The id of the user who created it. A call made with an API key is recorded as the key’s user.
`tenantId`	`uuid`	The id of the tenant it belongs to.
`id`	`uuid`	The unique id. Use it in `by-id` routes and wherever another object refers to this one.
`dateCreated`	`datetime`	When it was created, in UTC.
`dateUpdated`	`datetime`	When it was last changed, in UTC.

Example

{
  "capsule": {
    "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "version": 0
  },
  "dateStarted": "2026-10-26T12:00:00.0000000Z",
  "dateEnded": "2026-10-26T12:00:00.0000000Z",
  "status": "New",
  "failureDetails": "...",
  "virtualFileSystemMounts": [
    {
      "vfsId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "vfsNamespaceId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "mountName": "..."
    }
  ],
  "secretMounts": [
    {
      "secretName": "...",
      "mountName": "..."
    }
  ],
  "commands": [
    {
      "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "operationType": "Command",
      "command": "...",
      "arguments": [],
      "runAsUser": "...",
      "maximumDuration": "00:05:00",
      "status": "Pending",
      "outputStandard": "...",
      "outputError": "...",
      "exitCode": 0,
      "failureDetails": "...",
      "isAsync": false,
      "dateQueued": "2026-10-26T12:00:00.0000000Z",
      "dateStarted": "2026-10-26T12:00:00.0000000Z",
      "dateEnded": "2026-10-26T12:00:00.0000000Z",
      "outputStandardFullLength": 0,
      "outputErrorFullLength": 0,
      "timedOut": false
    }
  ],
  "hostname": "...",
  "createdUsers": [
    "..."
  ],
  "installedPackages": [
    "..."
  ],
  "defaultUser": "...",
  "triggeredByAutomatedActionId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "triggeredByAutomatedActionName": "...",
  "retentionLeaseActive": false,
  "retentionLeaseAppliedAtUtc": "2026-10-26T12:00:00.0000000Z",
  "retentionLeaseAppliedByUserId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "retentionLeaseAppliedByUserName": "...",
  "retentionLeaseNote": "...",
  "retentionLeaseInheritedFromProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "parentProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "parentProcessType": "App",
  "rootProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateRunnerPing": "2026-10-26T12:00:00.0000000Z",
  "waitingForLaneSinceUtc": "2026-10-26T12:00:00.0000000Z",
  "userCreatedById": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}

Where it’s used

capsuleRuns.get (GET /capsule-processes/by-id/{id})
capsuleRuns.list (GET /capsule-processes)
capsules.start (PUT /capsules/by-id/{id}/versions/{versionNumber}/start)
capsules.start (PUT /namespaces/{namespaceName}/capsules/by-name/{name}/versions/latest/start)