# trustlet

A **trustlet** is a built-in, internal component of the vHSM agent system which performs a specific, elevated action during VM setup, attestation, or  provisioning. Examples include:

* Installing a root filesystem or parts of it using "installer" trustlet
* Unlocking encrypted disks using "luks" trustlet
* Writing cloud-init or cloud-config style files using "cloud-config" or similar

Trustlets are specified in the agent’s configuration and are run automatically as part of machine startup or initialization. They often expect particular arguments such as URLs for rootfs tarballs, checksum, target paths, and others. 

#### Parameters

* **`source`** *(string, required)*
  * Defines the origin of the trustlet.
  * Commonly set to `"internal"` to indicate a built-in trustlet provided by the agent.
* **`name`** *(string, required)*
  * Identifies which trustlet logic to execute.
  * Examples:
    * `"installer"` – for installing software.
    * `"luks"` – for handling encrypted volumes.
    * `"cloud-config"` – for applying cloud-init–style configuration.
* **`arguments`** *(list of strings, required for most trustlets)*
  * Represents the inputs a trustlet needs to run.
  * Unlike named fields, trustlets consume these as **positional arguments**.
  * The exact values depend on the trustlet type, but commonly include:
    * Download URL / rootfs tarball – a URI, for example `https://.../ubuntu-rootfs.tar.gz`  pointing to a root filesystem, binary, or package to fetch.
    * **Checksum** – usually a SHA256 hash of the downloaded content, used for integrity verification.
    * Target path – the directory where the content should be unpacked or installed. For example, `/run/nextroot`.
    * Shell or script commands – optional commands for additional tasks such as extraction, configuration, or installation.
    * Config file paths – file paths for cloud-config or configuration fragments that need to be written or applied.

### Examples 

```hcl
trustlet {
  source = "internal"
  name   = "installer"
  arguments = [
    "<URL to Buckypaper VM rootfs>",
    "<checksum>",
    "/run/nextroot"
  ]
}
```

### Limitations & Caveats

* Not all trustlets support running arbitrary shell commands or compilation. Trustlets may accept a string in `arguments` but might not execute complex build commands.
* There is sometimes an implicit expectation that the downloaded rootfs or binary contains everything needed, including binaries, libraries, proper paths, etc. If not, the exec part will fail.
* Race conditions: exec blocks may start before a trustlet is fully complete if not properly ordered. Some versions might have `depends_on_trustlet` or similar but not all do.


---

# 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/nitride/tutorials/vhsm-agent/vhsm-agent-configurations/trustlet.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.