> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Store and Materialize Encrypted File Secrets in ironrun

> Store files like service account JSON as encrypted secrets. ironrun materializes them in isolated owner-only temp directories only while a command runs.

File secrets let you store entire credential files — JSON service accounts, TLS certificates, SSH keys — as encrypted blobs inside the ironrun vault. Unlike string secrets, these files need to be present on disk for the child process to read them. ironrun handles this safely: it writes the file to a unique owner-only temporary directory immediately before the command starts, injects only the **path** as an environment variable, and deletes the directory when the command finishes.

## How it works

1. You declare the file secret in `ironrun.yml` with a `kind: file` entry that specifies the env var name, the safe basename, and which commands may use it.
2. You store the file's contents using the TUI's **Add secret file** option — the encrypted blob lives in `~/.ironrun/vaults/`.
3. At execution time, ironrun:
   * Creates a unique owner-only temp directory **outside** the repository.
   * Writes the decrypted file with owner-only permissions (`600`).
   * Injects only the **path** (e.g. `/tmp/ironrun-abc123/service-account.json`) into the command's environment as the declared env var.
   * Streams output through the redactor, which strips literal contents, base64-encoded forms, and other common encodings of the file's bytes.
   * Removes the temp directory after the command succeeds, fails, times out, or is cancelled.

## Policy declaration

Declare the file secret in `ironrun.yml` alongside your string secrets:

```yaml theme={null}
secrets:
  service-account:
    env: GOOGLE_APPLICATION_CREDENTIALS
    kind: file
    filename: service-account.json
    allow: [integration-test]

commands:
  - id: integration-test
    argv: [go, test, ./integration/...]
    secrets: [service-account]
```

* `env` — the environment variable the command reads to find the file path.
* `kind: file` — marks this as a file secret rather than a string value.
* `filename` — the safe basename that ironrun uses when writing the temp file.
* `allow` — command IDs that are permitted to receive this file secret.
* `secrets` — on the command, lists which secret entries to materialize.

## Adding the file through the TUI

Open the terminal control room:

```bash theme={null}
ironrun
```

Navigate to the environment where you want to store the file, open the action palette (`/`), and choose **Add secret file**. ironrun prompts for the source path, reads the file, encrypts it, and stores the blob in the vault. The source file is not deleted.

## What ironrun rejects

When you add a file secret or at execution time, ironrun validates the source and target:

* **Symlinks** — rejected; ironrun follows no symlinks.
* **Path traversal** — filenames containing `..` or `/` are rejected.
* **Unsafe basenames** — names that would be dangerous in a temp directory (e.g. hidden files with dangerous extensions).
* **Permissive source files** — source files readable by group or others are rejected.
* **Duplicate targets** — two secrets cannot write to the same path in the same temp directory.

## Redaction coverage

ironrun redacts the following from command output before it reaches the agent:

* The literal bytes of the file's contents.
* Base64-encoded forms (standard and URL-safe).
* Hex-encoded forms.
* URL-encoded forms.
* A warn-only entropy scan flags high-entropy tokens that match the shape of the file's content but slip through other patterns.

## Cleanup and stale remnants

The temp directory is removed after:

* The command exits (success or failure).
* The command is killed due to a `ttl` timeout.
* The command is cancelled by a revocation.

On startup, ironrun scans for and removes validated stale temp directories left behind by a previous crash or unexpected termination.

<Warning>
  Temporary plaintext necessarily exists on disk for the duration of the command. SSD media may not physically erase overwritten sectors even after the directory is deleted. To limit exposure: set a short `ttl` on commands that use file secrets, and revoke agent leases as soon as the work is done.
</Warning>