# Environments

## What environments are for

When an agent moves from a developer's laptop to a staging review and finally into production, the surrounding configuration should change with it: different credentials, different network rules, different pre-installed packages. An **environment** is the Ren primitive that captures those differences.

Each environment is a named, versionable configuration record that a [pod](/docs/deep-dives/concepts/compute/pods/) can point to. When a pod references an environment, that environment's settings are applied to the sandbox the pod runs in: from which hosts the agent may contact, to which system packages are installed before the agent starts.

## How environments relate to pods and projects

A [pod](/docs/deep-dives/concepts/compute/pods/) can point to an environment; its sandbox is then bootstrapped with that environment's networking rules and packages. Without one, a pod runs with unrestricted networking and no extra packages. A [project](/docs/deep-dives/concepts/compute/projects/) inherits its pod's environment.

One environment can be shared across many pods (every staging pod might point to the same "staging" environment), or each pod can carry its own.

## What an environment controls

### Networking

An environment has two networking modes:

- **Unrestricted**: the sandbox can reach any host. Fine for development or trusted internal workloads.
- **Limited**: outbound access is gated by three controls:
  - Whether the sandbox may connect to MCP servers.
  - Whether it may reach package registries (npm, PyPI, crates.io, etc.).
  - An explicit allow-list of hostnames it may contact.

Limited networking is the foundation for production isolation: an agent that should only talk to your internal API and your MCP servers can be locked down so it can't exfiltrate data to an arbitrary endpoint.

### Packages

An environment can pre-install system and language packages into the sandbox before the agent starts, so the first run already has the tools it needs. Each package manager takes a list of package names:

| Key     | Package manager     | Example                    |
| ------- | ------------------- | -------------------------- |
| `apt`   | APT (Debian/Ubuntu) | `curl`, `git`              |
| `npm`   | npm (global)        | `typescript`, `prettier`   |
| `pip`   | pip (user install)  | `requests`, `black`        |
| `cargo` | Cargo (Rust)        | `ripgrep`, `fd-find`       |
| `gem`   | RubyGems            | `rubocop`                  |
| `go`    | Go install          | `golang.org/x/tools/gopls` |

Environments run on Ren-managed cloud infrastructure.

## Scoping resources per stage

An environment also acts as a boundary for resources that should differ across deployment stages:

- **Credentials**: scope a secret to an environment so a production agent never uses a development API key.
- **Agent versions**: pin different versions per environment for safe promotion from staging to production.
- **File stores**: keep production data separate from development artifacts.

A pod bound to an environment can only access resources that match that environment (or are environment-agnostic).

## Lifecycle

- **Create**: define a name, networking, and optional packages.
- **Update**: change networking or packages at any time; pods pick up the change on their next sync.
- **Archive**: remove it from new-pod selection. Pods already using it keep running on their last-known-good configuration.

## Current state

Environments are under active development. Networking and packages are available today; detailed guides for common patterns (e.g. "lock down a production agent") are still being written.