Dynamic Secrets

Dynamic Secrets allow you to generate credentials on-the-fly, when they are needed, rather than storing static, long-lived credentials in RunEnv.

How it works

  1. Configure a Provider: You configure RunEnv with root access to a database (e.g., PostgreSQL) or cloud provider (e.g., AWS IAM).
  2. Define a Role: You define a role within RunEnv, such as readonly-db-user. This role contains the SQL statements required to create a user and grant it specific, limited permissions.
  3. Request a Lease: Your application requests a "lease" for this role.
  4. JIT Generation: RunEnv connects to the database, creates a brand new user with a strong, random password, grants it the requested permissions, and returns these credentials to your application.
  5. Revocation: When the lease expires (e.g., after 1 hour), RunEnv connects back to the database and drops the user, destroying the credential forever.

Supported Providers

  • Databases: PostgreSQL, MySQL, MongoDB, Redis
  • Cloud Providers: AWS IAM (STS assume role), GCP Service Accounts, Azure Service Principals

Sidecar Lease Autopilot

For long-running services, use runenv-agent instead of a terminal-bound lease watch process. The sidecar is enrolled for one project environment, authenticates with a rag_ token, syncs only leases owned by that sidecar, and keeps the latest credential bundle in memory.

When a credential is renewed or replaced, the sidecar increments its delivery version and runs a configured reload hook. Your application should refresh its own database pool or cloud client from the sidecar memory endpoint. RunEnv does not mutate an already-running process environment.

On graceful shutdown, the sidecar asks RunEnv to revoke all active sidecar-owned leases through the provider adapter. If the host crashes or the process is force-killed, stale-agent monitoring and the lease reaper remain the fallback.

Example: PostgreSQL Dynamic Credentials

Assume you've configured a PostgreSQL provider and a role called analytics-reader.

You can request a credential using the CLI:

runenv lease request --role analytics-reader --ttl 1h

Output:

{
  "lease_id": "ls_987xyz",
  "valid_until": "2026-04-22T12:00:00Z"
}

Credential values are intentionally omitted from documentation and must not be logged, copied into prompts, or committed to source control.

If you finish your task early, you can manually revoke the lease:

runenv lease revoke --lease-id ls_987xyz