Capsule runs

14 calls. Every request needs the Authorization header: see the overview.

`capsuleRuns.list`

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.

Response: CapsuleProcess[] (200)

curl -X GET "https://api.maitento.com/capsule-processes" \
  -H "Authorization: $MAITENTO_AUTH"

const runs = await mt.capsuleRuns.list();

mt.capsule_runs.list()

`capsuleRuns.get`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: CapsuleProcess (200)

curl -X GET "https://api.maitento.com/capsule-processes/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const run = await mt.capsuleRuns.get("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f");

mt.capsule_runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")

`capsuleRuns.exec`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: CapsuleProcessRunCommandRequest

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 (200)

curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/commands" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"command":"..."}'

const command = await mt.capsuleRuns.exec("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { command: "python3", arguments: ["report.py"] }); // or mt.capsuleRuns.execAndWait(...)

mt.capsule_runs.exec("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "python3", ["-c", "print(42)"])  # or mt.capsule_runs.exec_and_wait(...)

`capsuleRuns.getCommand`

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.

Path parameters

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

Response: CapsuleProcessCommand (200)

curl -X GET "https://api.maitento.com/capsule-processes/by-id/<id>/commands/<commandId>" \
  -H "Authorization: $MAITENTO_AUTH"

const command = await mt.capsuleRuns.getCommand("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70");

mt.capsule_runs.get_command("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70")

`capsuleRuns.mountSecret`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: CapsuleProcessMountSecretRequest

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 (200)

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":"..."}'

await mt.capsuleRuns.mountSecret("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { secretName: "github-token", mountName: "github" });

mt.capsule_runs.mount_secret("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", secret_name="github-token", mount_name="github")

`capsuleRuns.unmountSecret`

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.

Path parameters

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

Response: CapsuleProcessCommand (200)

curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/secrets/<mountName>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.capsuleRuns.unmountSecret("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "github");

mt.capsule_runs.unmount_secret("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "github")

`capsuleRuns.mountVfs`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: CapsuleProcessMountVfsRequest

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 (200)

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":"..."}'

await mt.capsuleRuns.mountVfs("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { vfsId: "e9d8c7b6-a5f4-4e3d-8c2b-1a0f9e8d7c6b", vfsNamespaceId: "b5f3d1a9-7e6c-4b4a-9a2e-8c0d1f3e5a7b", mountName: "workspace" });

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`

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.

Path parameters

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

Response: CapsuleProcessCommand (200)

curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/mounts/vfs/<mountName>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.capsuleRuns.unmountVfs("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "workspace");

mt.capsule_runs.unmount_vfs("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "notes")

`capsuleRuns.installPackage`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: CapsuleProcessInstallPackageRequest

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

Response: CapsuleProcessCommand (200)

curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/packages" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"packageName":"..."}'

await mt.capsuleRuns.installPackage("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { packageName: "jq" });

mt.capsule_runs.install_package("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "ripgrep")

`capsuleRuns.removePackage`

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.

Path parameters

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

Response: CapsuleProcessCommand (200)

curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/packages/<packageName>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.capsuleRuns.removePackage("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "jq");

mt.capsule_runs.remove_package("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "ripgrep")

`capsuleRuns.terminate`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: CapsuleProcessCommand (200)

curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/terminate" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.capsuleRuns.terminate("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f");

mt.capsule_runs.terminate("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")

`capsuleRuns.addUser`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: CapsuleProcessAddUserRequest

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 (200)

curl -X POST "https://api.maitento.com/capsule-processes/by-id/<id>/users" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"username":"..."}'

await mt.capsuleRuns.addUser("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", { username: "analyst", sudoAsUsers: [] });

mt.capsule_runs.add_user("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "builder")

`capsuleRuns.removeUser`

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.

Path parameters

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

Response: CapsuleProcessCommand (200)

curl -X DELETE "https://api.maitento.com/capsule-processes/by-id/<id>/users/<username>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.capsuleRuns.removeUser("c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "analyst");

mt.capsule_runs.remove_user("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "builder")

`capsuleRuns.listActive`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Response: CapsuleProcessWithDetails[] (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/capsules/processes" \
  -H "Authorization: $MAITENTO_AUTH"

const active = await mt.capsuleRuns.listActive({ namespace: "support" });

mt.capsule_runs.list_active(namespace="demo")