# Capsule runs

14 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `capsuleRuns.list`

```http
GET /capsule-processes
```

Every capsule run of the tenant (unbounded; prefer `runs.list({ types: ["Capsule"] })`).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fcapsule-processes).

**Response:** [`CapsuleProcess`](https://docs.maitento.com/reference/types/capsule-process.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/capsule-processes" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const runs = await mt.capsuleRuns.list();
```
```python title="Python"
mt.capsule_runs.list()
```

## `capsuleRuns.get`

```http
GET /capsule-processes/by-id/{id}
```

The run with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`CapsuleProcess`](https://docs.maitento.com/reference/types/capsule-process.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/capsule-processes/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const run = await mt.capsuleRuns.get("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f");
```
```python title="Python"
mt.capsule_runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```

## `capsuleRuns.exec`

```http
POST /capsule-processes/by-id/{id}/commands
```

Queues a command and returns it `Pending`; it runs once the capsule is ready, after the commands queued before it. `command` is shell text, run by the user's login shell from `/`. Each of `arguments` reaches the program as one word, exactly as given (spaces, quotes and `$` included): to pipe or redirect, run `sh` with `["-c", "<line>"]`, or put the whole line in `command`. To get the result, use `execAndWait` (or `getCommand`).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fcommands).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`CapsuleProcessRunCommandRequest`](https://docs.maitento.com/reference/types/capsule-process-run-command-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `command` | `string` | yes | The command: shell text run by the user's login shell, from `/` — usually a program name, but it may be a whole command line (pipes, redirects and variables are then the shell's). |
| `arguments` | `string[]` |  | The command's arguments. Each is passed as one literal word, quoted for the shell as needed, so spaces, quotes, `$`, globs and operators in an argument reach the program exactly as given. To pipe or redirect, run `sh` with arguments `["-c", "<line>"]`, or put the line in `command`. |
| `runAsUser` | `string \| null` |  | The user to run it as: one of the capsule's users or one added to the run. Null: the default user. |
| `maximumDuration` | `timespan \| null` |  | The longest the command may run before it is stopped. Null: five minutes. |
| `async` | `boolean` |  | Run the command in the background: the capsule moves on to the next command without waiting for this one, and records its result when it ends. |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/commands" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"command":"..."}'
```
```ts title="TypeScript"
const command = await mt.capsuleRuns.exec("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { command: "python3", arguments: ["report.py"] }); // or mt.capsuleRuns.execAndWait(...)
```
```python title="Python"
mt.capsule_runs.exec("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "python3", ["-c", "print(42)"])  # or mt.capsule_runs.exec_and_wait(...)
```

## `capsuleRuns.getCommand`

```http
GET /capsule-processes/by-id/{id}/commands/{commandId}
```

One command (or operation) of a capsule run, with its status and output. One still queued or running when the run ended reads as `AbortedOnTermination`. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fcommands%2F%7BcommandId%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `commandId` | `uuid` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/capsule-processes/by-id/<id>/commands/<commandId>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const command = await mt.capsuleRuns.getCommand("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70");
```
```python title="Python"
mt.capsule_runs.get_command("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70")
```

## `capsuleRuns.mountSecret`

```http
POST /capsule-processes/by-id/{id}/mounts/secrets
```

Mounts a secret as a file.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fmounts%2Fsecrets).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`CapsuleProcessMountSecretRequest`](https://docs.maitento.com/reference/types/capsule-process-mount-secret-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `secretName` | `string` | yes | The name of the secret to mount. |
| `mountName` | `string` | yes | The file name: the secret's value is written to `/mnt/secrets/<mountName>`. Letters, digits, `_` and `-`. |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/secrets" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"secretName":"...","mountName":"..."}'
```
```ts title="TypeScript"
await mt.capsuleRuns.mountSecret("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { secretName: "github-token", mountName: "github" });
```
```python title="Python"
mt.capsule_runs.mount_secret("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", secret_name="github-token", mount_name="github")
```

## `capsuleRuns.unmountSecret`

```http
DELETE /capsule-processes/by-id/{id}/mounts/secrets/{mountName}
```

Unmounts a secret.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fmounts%2Fsecrets%2F%7BmountName%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `mountName` | `string` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/secrets/<mountName>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsuleRuns.unmountSecret("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "github");
```
```python title="Python"
mt.capsule_runs.unmount_secret("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "github")
```

## `capsuleRuns.mountVfs`

```http
POST /capsule-processes/by-id/{id}/mounts/vfs
```

Mounts a virtual file system.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fmounts%2Fvfs).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`CapsuleProcessMountVfsRequest`](https://docs.maitento.com/reference/types/capsule-process-mount-vfs-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `vfsId` | `uuid` | yes | The id of the virtual file system to mount. |
| `vfsNamespaceId` | `uuid` | yes | The id of the namespace the virtual file system is in. |
| `mountName` | `string` | yes | Where it appears: `/mnt/<mountName>`. Letters, digits, `_` and `-`, not already in use. |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/vfs" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"vfsId":"...","vfsNamespaceId":"...","mountName":"..."}'
```
```ts title="TypeScript"
await mt.capsuleRuns.mountVfs("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { vfsId: "e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b", vfsNamespaceId: "b5f3d1a9-7e6c-4b4a-9a2e-8c0d1f3e5a7b", mountName: "workspace" });
```
```python title="Python"
mt.capsule_runs.mount_vfs("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", vfs_id="7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b", vfs_namespace_id="0f1e2d3c-4b5a-4968-8776-655443322110", mount_name="notes")
```

## `capsuleRuns.unmountVfs`

```http
DELETE /capsule-processes/by-id/{id}/mounts/vfs/{mountName}
```

Unmounts a virtual file system.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fmounts%2Fvfs%2F%7BmountName%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `mountName` | `string` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/vfs/<mountName>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsuleRuns.unmountVfs("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "workspace");
```
```python title="Python"
mt.capsule_runs.unmount_vfs("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "notes")
```

## `capsuleRuns.installPackage`

```http
POST /capsule-processes/by-id/{id}/packages
```

Installs a package.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fpackages).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`CapsuleProcessInstallPackageRequest`](https://docs.maitento.com/reference/types/capsule-process-install-package-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `packageName` | `string` | yes | The package name, such as `jq`: lowercase letters, digits, `+`, `-` and `.`. |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/packages" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"packageName":"..."}'
```
```ts title="TypeScript"
await mt.capsuleRuns.installPackage("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { packageName: "jq" });
```
```python title="Python"
mt.capsule_runs.install_package("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "ripgrep")
```

## `capsuleRuns.removePackage`

```http
DELETE /capsule-processes/by-id/{id}/packages/{packageName}
```

Removes a package.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fpackages%2F%7BpackageName%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `packageName` | `string` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/packages/<packageName>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsuleRuns.removePackage("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "jq");
```
```python title="Python"
mt.capsule_runs.remove_package("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "ripgrep")
```

## `capsuleRuns.terminate`

```http
POST /capsule-processes/by-id/{id}/terminate
```

Terminates the capsule.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fterminate).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/terminate" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsuleRuns.terminate("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f");
```
```python title="Python"
mt.capsule_runs.terminate("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```

## `capsuleRuns.addUser`

```http
POST /capsule-processes/by-id/{id}/users
```

Adds a user.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fusers).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Request body:** [`CapsuleProcessAddUserRequest`](https://docs.maitento.com/reference/types/capsule-process-add-user-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | `string` | yes | The user name: lowercase letters, digits, `_` and `-`, starting with a letter or `_`, at most 32 characters, and not `root`. |
| `sudoAsUsers` | `string[]` |  | Other users of the capsule this user may run commands as, with `sudo`. |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/users" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"username":"..."}'
```
```ts title="TypeScript"
await mt.capsuleRuns.addUser("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { username: "analyst", sudoAsUsers: [] });
```
```python title="Python"
mt.capsule_runs.add_user("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "builder")
```

## `capsuleRuns.removeUser`

```http
DELETE /capsule-processes/by-id/{id}/users/{username}
```

Removes a user.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fcapsule-processes%2Fby-id%2F%7Bid%7D%2Fusers%2F%7Busername%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `username` | `string` | yes |  |

**Response:** [`CapsuleProcessCommand`](https://docs.maitento.com/reference/types/capsule-process-command.md) (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/users/<username>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.capsuleRuns.removeUser("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "analyst");
```
```python title="Python"
mt.capsule_runs.remove_user("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "builder")
```

## `capsuleRuns.listActive`

```http
GET /namespaces/{namespaceName}/capsules/processes
```

The capsule runs of the namespace that have not finished.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fcapsules%2Fprocesses).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Response:** [`CapsuleProcessWithDetails`](https://docs.maitento.com/reference/types/capsule-process-with-details.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/capsules/processes" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const active = await mt.capsuleRuns.listActive({ namespace: "support" });
```
```python title="Python"
mt.capsule_runs.list_active(namespace="demo")
```