# 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`](https://docs.maitento.com/reference/types/version-reference.md) | 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`](https://docs.maitento.com/reference/types/capsule-process-status.md) | Where the run is in its life. |
| `failureDetails` | `string \| null` | Why the run failed, when its status is `Error`. Null otherwise. |
| `virtualFileSystemMounts` | [`CapsuleVirtualFileSystemMount`](https://docs.maitento.com/reference/types/capsule-virtual-file-system-mount.md)`[]` | The virtual file systems mounted in the run, each at `/mnt/<mountName>`. |
| `secretMounts` | [`CapsuleSecretMount`](https://docs.maitento.com/reference/types/capsule-secret-mount.md)`[]` | The secrets mounted in the run, each as the file `/mnt/secrets/<mountName>`. |
| `commands` | [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md)`[]` | 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`](https://docs.maitento.com/reference/types/process-type.md)`\| 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

```json
{
  "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`](https://docs.maitento.com/reference/api/capsule-runs.md) (`GET /capsule-processes/by-id/{id}`)
- [`capsuleRuns.list`](https://docs.maitento.com/reference/api/capsule-runs.md) (`GET /capsule-processes`)
- [`capsules.start`](https://docs.maitento.com/reference/api/capsules.md) (`PUT /capsules/by-id/{id}/versions/{versionNumber}/start`)
- [`capsules.start`](https://docs.maitento.com/reference/api/capsules.md) (`PUT /namespaces/{namespaceName}/capsules/by-name/{name}/versions/latest/start`)