Skip to main content
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:
  • 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:
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.
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.