> ## 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.

# Managing Project Environments and Secrets in ironrun

> ironrun organizes secrets into named environments like dev, staging, and session. Switch between them, create sessions, and manage the full lifecycle.

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**.

<Note>
  `.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.
</Note>

## Core environment commands

<Steps>
  <Step title="Create a new environment">
    ```bash theme={null}
    ironrun new staging
    ```

    Creates and switches to a new persistent environment named `staging`.
  </Step>

  <Step title="Switch environments">
    ```bash theme={null}
    ironrun use dev
    ```

    Sets `dev` as the active environment. Subsequent `ironrun run` calls and `run_sealed` calls from the agent will use `dev`'s secrets.
  </Step>

  <Step title="List environments">
    ```bash theme={null}
    ironrun envs
    ```

    Lists environment names and their configured key names. Values are never shown.
  </Step>

  <Step title="Check project status">
    ```bash theme={null}
    ironrun status
    ```

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

  <Step title="Create a temporary session environment">
    ```bash theme={null}
    ironrun session
    ```

    Creates and switches to a 24-hour temporary environment. Session environments expire automatically and are cleaned up by `ironrun env prune`.
  </Step>
</Steps>

## Running with a specific environment

Use `--set` to override the active environment for a single run without switching globally:

```bash theme={null}
ironrun run --set staging deploy
```

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:

<CodeGroup>
  ```bash Initialization theme={null}
  ironrun env init dev
  ```

  ```bash Adding secrets theme={null}
  ironrun env set dev KEY
  # masked prompt — the value is never shown in the terminal
  ```

  ```bash Cloning theme={null}
  ironrun env clone dev staging
  # copies all keys from dev into staging (values are copied encrypted)
  ```
</CodeGroup>

<CodeGroup>
  ```bash Temporary environments theme={null}
  ironrun env create session --temporary --ttl 8h
  ironrun env use session
  ```

  ```bash Cleanup theme={null}
  ironrun env prune
  # removes expired temporary environments
  ```
</CodeGroup>

<CodeGroup>
  ```bash Rotating a value theme={null}
  ironrun env rotate staging DATABASE_URL
  # masked prompt — replaces the value for DATABASE_URL in staging
  ```

  ```bash Deleting a single key theme={null}
  ironrun env delete staging OLD_KEY
  # permanently removes ONE secret key from the staging environment
  ```

  ```bash Removing an entire environment theme={null}
  ironrun env remove staging
  # permanently deletes the staging environment and all its secrets
  ```

  ```bash Health check theme={null}
  ironrun env doctor
  # validates vault integrity and credential manager access
  ```
</CodeGroup>

### Full subcommand reference

| Command                                           | Description                                                        |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| `ironrun env init dev`                            | Initialize a new environment named `dev`                           |
| `ironrun env set dev KEY`                         | Add or update a secret in `dev` via masked prompt                  |
| `ironrun env create staging`                      | Create a new environment named `staging`                           |
| `ironrun env clone dev staging`                   | Copy all keys from `dev` to `staging`                              |
| `ironrun env use staging`                         | Switch the active environment to `staging`                         |
| `ironrun env list`                                | List all environment names and key counts, never values            |
| `ironrun env status`                              | Value-blind summary of the active environment's keys               |
| `ironrun env create session --temporary --ttl 8h` | Create a temporary environment that expires in 8 hours             |
| `ironrun env prune`                               | Remove all expired temporary environments                          |
| `ironrun env rotate <name> <key>`                 | Replace a single secret value via masked prompt                    |
| `ironrun env delete <name> <key>`                 | Permanently delete one secret key from an environment              |
| `ironrun env remove <name>`                       | Permanently remove an entire environment and all its secrets       |
| `ironrun env import <name> <file>`                | Import secrets from a dotenv file into a named environment         |
| `ironrun env export <name> <path>`                | Write a `KEY=` template file for the named environment (no values) |
| `ironrun env doctor`                              | Validate vault integrity and credential manager health             |

## 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.

```bash theme={null}
# Create a temporary environment with an 8-hour TTL
ironrun env create session --temporary --ttl 8h

# Switch to it
ironrun env use session

# ... do your work ...

# Clean up all expired temporary environments
ironrun env prune
```

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).

<Warning>
  `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.
</Warning>