# Environments service

> How Nested Environments create short-lived machines for agents: the manifest, Docker and Kubernetes runtimes, lifetimes, and isolation.

Section: Platform · Updated: 2026-11-19 · Canonical: https://nested.me/docs/environments-platform

## What it is

Environments give agents and people short-lived machines to run and test apps. Each environment is one virtual machine running either a Docker daemon or a single-node Kubernetes (k3s), optionally with your app deployed from one manifest. Agents use it to bring up a stack, run tests against it, and share a preview link.

Environments is a separate service, installed with your cell and enabled per team by an operator.

> [!IMPORTANT]
> Environment machines do not run inside your Kubernetes cluster. They run on a cloud provider account that the Environments service is configured with; the shipped driver provisions DigitalOcean droplets. Source code and secrets you send to an environment go to that machine.

## Isolation and networking

- **One machine per environment.** Environments never share a machine.
- **No inbound traffic.** Every inbound port is closed. An agent on the machine dials out to the Environments gateway, and all access — Docker API, Kubernetes API, logs, exec, preview URLs — is relayed through that connection.
- **Short-lived credentials.** Connecting returns a Docker host address or kubeconfig that works only through the gateway, for a limited time. No credential leaves the machine.
- **Previews need sign-in.** Preview links require Nested sign-in; public preview links are not available.

## The manifest

A manifest is an envelope around what you already have — Dockerfiles, Compose files, Helm charts, Kustomize directories — not a new way to define containers.

| Field | Meaning |
|---|---|
| `spec.runtime` | `docker` or `kubernetes` |
| `spec.resources.type` | A named machine type from the catalog |
| `spec.lifetime` | `ttl` (required), optional `idle`, and a policy |
| `spec.sources` | Git repositories or uploaded archives |
| `spec.secrets` | Secret names only; values are set through the API |
| `spec.components` | `compose` or `image` on Docker; `image`, `helm`, `kustomize`, or `manifests` on Kubernetes |
| `spec.expose` | Ports to publish as team preview links |

Builds run on the machine’s own Docker, so no registry is needed. Components apply in dependency order. A manifest can be up to 256 KiB, with up to 20 components and 10 exposed ports.

## Lifetimes

The server, not the machine, enforces when an environment ends:

- **Agent environments** end with the task that created them by default, after a one-hour grace period. An agent can ask for a fixed lifetime instead.
- **Environments you create** use a fixed lifetime (`ttl`).
- An optional idle timeout ends an environment with no activity.
- A periodic sweep destroys any machine that has no live environment, so a crash cannot leave paid machines behind.

Operators set per-team ceilings: by default 3 concurrent environments and 8 hours maximum lifetime, up to 50 and 72 hours. An agent may hold 3 live environments per task. Anyone in the team can view and create environments; the creator, the manager, and team owners and admins can extend or destroy them.

## Agent tools

When an operator enables Environments for agents, every task session gets an `environments` MCP server with 13 tools, including `env_validate`, `env_create`, `env_apply`, `env_logs`, `env_exec`, `env_connect`, `env_extend`, and `env_destroy`. Creating an environment is idempotent per task. Agents also get skills for writing manifests and debugging failed environments.

## Secrets

Secret values are encrypted with envelope encryption: a fresh key per value, sealed with AES-256-GCM under a rotatable key ring. They are delivered only to the machine’s agent and never returned by reads.

To use environments in the app, see the Environments page in your account menu, when your team has it enabled.

## Questions

### Do Nested environments run in my cluster?

No. Each environment is a separate virtual machine on the cloud provider the Environments service is configured with. It accepts no inbound traffic and is reached only through the Environments gateway.

### How long does an environment live?

An agent’s environment ends with its task by default. Others end at their time-to-live. Team ceilings default to 8 hours.

### Can I share a public preview link?

Not yet. Preview links require Nested sign-in.

## Related

- [Architecture](https://nested.me/docs/architecture)
- [Security model](https://nested.me/docs/security)
- [Agent runtime](https://nested.me/docs/agent-runtime)
- [Install Nested](https://nested.me/docs/install)
