Skip to main content
Environments are named collections of encrypted secrets. You might have a dev environment with local database credentials, a staging environment with credentials for your staging cluster, and a short-lived session environment for a one-day task. The agent always sees only the active environment’s key names — never values — and ironrun injects values only into child processes, never into the agent’s shell.

​
Where things live

Ironrun keeps a strict separation between project metadata and secret values:
  • Encrypted vault — lives at ~/.ironrun/vaults/, outside your repository. Every environment has a rotating data key wrapped by a project root key stored in the native OS credential manager. Secret values never leave this vault in plaintext.
  • Project metadata — lives at .ironrun/ inside your repository. Contains environment names, entry names, approved command history, and agent access state. Contains no secret values.
.ironrun/ project metadata is safe to commit to version control. The vault at ~/.ironrun/vaults/ is not in the repo and should never be committed.

​
Core environment commands

1

Create a new environment

Creates and switches to a new persistent environment named staging.
2

Switch environments

Sets dev as the active environment. Subsequent ironrun run calls and run_sealed calls from the agent will use dev’s secrets.
3

List environments

Lists environment names and their configured key names. Values are never shown.
4

Check project status

Prints a value-blind summary of the active environment: which environment is active, what keys are configured, and the project identity.
5

Create a temporary session environment

Creates and switches to a 24-hour temporary environment. Session environments expire automatically and are cleaned up by ironrun env prune.

​
Running with a specific environment

Use --set to override the active environment for a single run without switching globally:
This runs the deploy command with staging’s secrets, then leaves your active environment unchanged.

​
Advanced environment subcommands

The ironrun env subcommand covers the full environment lifecycle:

​
Full subcommand reference

​
Temporary session environments

Session environments are created with --temporary and expire automatically after their TTL (24 hours by default). They are useful for short-lived tasks where you want to give an agent access to a specific set of credentials without touching your persistent dev or staging environments.
Temporary environments are pinned to the MCP session that uses them. A server restart creates a new session; old temporary access grants do not transfer.

​
Import and export

ironrun import .env and ironrun env import <name> <file> accept owner-only dotenv files, display key names but never values, confirm before writing, verify the encrypted result, and warn that the plaintext source file still exists (ironrun never deletes it for you).
ironrun env export <name> <path> writes only a KEY= template — environment variable names with empty values. It never exports plaintext secret values. There is no command in ironrun that reveals or exports plaintext values.