# /sys/plugins/runtimes/catalog

The `/sys/plugins/runtimes/catalog` manages plugin runtimes in your Vault catalog by reading, registering, updating, and removing plugin runtime information. Plugin runtimes must be registered before use, and once registered, backends can use the plugin runtime by referencing them when registering a plugin.

### LIST plugin runtimes

The list endpoint returns a list of the plugin runtimes in the catalog.

* **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities.

| Method | Path                                       |
| ------ | ------------------------------------------ |
| `LIST` | `/sys/plugins/runtimes/catalog`            |
| `GET`  | `/sys/plugins/runtimes/catalog`            |
| `LIST` | `/sys/plugins/runtimes/catalog?type=:type` |
| `GET`  | `/sys/plugins/runtimes/catalog?type=:type` |

#### Parameters

* `type` `(string: <required>)` – Specifies the plugin runtime type to list. Currently only accepts "container".

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST
    http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog
```

#### Sample response

```json
{
  "data": {
    "runtimes": [
      {
        "name": "example-plugin-runtime",
        "type": "container",
        "oci_runtime": "example-oci-runtime",
        "cgroup_parent": "/examplelimit/",
        "cpu_nanos": 1000,
        "memory_bytes": 10000000
      },
      ...
    ]
  }
}
```

### Register plugin runtime

The registration endpoint registers a new plugin runtime, or updates an existing one with the supplied type and name.

* **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities.

| Method | Path                                        |
| ------ | ------------------------------------------- |
| `POST` | `/sys/plugins/runtimes/catalog/:type/:name` |

#### Parameters

* `type` `(string: <required>)` – Specifies the plugin runtime type. Currently only accepts "container".
* `name` `(string: <required>)` – Part of the request URL. Specifies the plugin runtime name. Use the runtime name to look up plugin runtimes in the catalog.
* `oci_runtime` `(string: <optional>)` – Specifies OCI-compliant container runtime to use. Default is "runsc", gVisor's OCI runtime.
* `cgroup_parent` `(string: <optional>)` – Specifies the parent cgroup to set for each container. Use the cgroup to control the total resource usage for a group of plugins.
* `cpu_nanos` `(int: <optional>)` – Specifies cpu limit to set per container in billionths of a CPU. Defaults to no limit.
* `memory_bytes` `(int: <optional>)` – Specifies memory limit to set per container in bytes. Defaults to no limit.

#### Sample payload

```json
{
  "oci_runtime": "example-oci-runtime",
  "cgroup_parent": "/examplelimit/",
  "cpu_nanos": 1000,
  "memory_bytes": 10000000
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime
```

### Read plugin runtime

The read endpoint returns the configuration data for the plugin runtime with the given type and name.

* **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities.

| Method | Path                                        |
| ------ | ------------------------------------------- |
| `GET`  | `/sys/plugins/runtimes/catalog/:type/:name` |

#### Parameters

* `type` `(string: <required>)` – Specifies the type of this plugin runtime. Currently only accepts "container".
* `name` `(string: <required>)` – Part of the request URL. Specifies the name of the plugin runtime to retrieve.

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime
```

#### Sample response

```json
{
  "data": {
    "name": "example-plugin-runtime",
    "type": "container",
    "oci_runtime": "example-oci-runtime",
    "cgroup_parent": "/examplelimit/",
    "cpu_nanos": 1000,
    "memory_bytes": 10000000
  }
}
```

### Remove plugin runtime from catalog

The remove endpoint removes the plugin runtime with the given type and name. Note that the request will fail if any registered plugin references the plugin runtime.

* **`sudo` required** – This endpoint requires `sudo` capability in addition to any path-specific capabilities.

| Method   | Path                                        |
| -------- | ------------------------------------------- |
| `DELETE` | `/sys/plugins/runtimes/catalog/:type/:name` |

#### Parameters

* `type` `(string: <required>)` – Specifies the type of this plugin runtime. Currently only accepts "container".
* `name` `(string: <required>)` – Part of the request URL. Specifies the name of the plugin runtime to delete.

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/plugins/runtimes/catalog/container/example-plugin-runtime
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/api/system-backend/sys-plugins-runtimes-catalog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.