---
title: "environments"
summary: "Where the application runs, the SSH target, per-environment overrides, and the policy governing deployment there."
status: shipped
generated: true
read_when:
  - "Adding a staging or production environment"
  - "Requiring local confirmation, a minimum runner version, or a migration backup report"
  - "Working out which fields an environment override may change"
---

> **`environments` is required**
>
> A project file that does not declare `environments` fails to load.

This page is generated from the same Go declarations the loader enforces, so it
cannot drift from what `ob validate` accepts.

## Fields on this page

`allow_agent_proposals` · `base_path` · `env_files` · `file` · `host` · `migration_backup_key_material` · `migration_backup_maximum_age` · `minimum_onebox_version` · `minimum_plan_schema` · `overrides` · `policy` · `port` · `provider` · `require_approval` · `require_migration_backup` · `require_migration_restore_test` · `server` · `services` · `user` · `workloads`

## Reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `<name>.base_path` | string | — | Environment-specific replacement for the project base_path. Expects an absolute path with no control character or shell metacharacter. |
| `<name>.env_files` | list | — | Default ordered environment-file list for application, worker, and job workloads in this environment. |
| `<name>.env_files[].file` `*` | string | — | Repository-relative environment file path. Expects a path inside the repository, with no control character or shell metacharacter. |
| `<name>.env_files[].provider` | `sops` | — | Decryptor used before staging the file. The supported encrypted provider is sops. |
| `<name>.overrides` | object | — | Environment-specific operational tuning. Overrides cannot change workload identity or data semantics. |
| `<name>.overrides.services` | map | — | Allowed service tuning keyed by service name: resources and settings. |
| `<name>.overrides.workloads` | map | — | Allowed workload tuning keyed by workload name: replicas, resources, env, env_files, strategy, and routes. |
| `<name>.policy` | object | — | Approval, runner compatibility, and migration-backup requirements for this environment. |
| `<name>.policy.allow_agent_proposals` | boolean | `true` | Declared permission for agent-authored proposals. The current CLI does not distinguish agent identity; execution remains approval-gated. |
| `<name>.policy.migration_backup_key_material` | list | — | Names of key material whose usability must be covered by the migration backup report. |
| `<name>.policy.migration_backup_maximum_age` | string | `24h` | Maximum age of a backup report accepted for a migration. Expects a duration such as 30s, 5m, 1h30m or 14d. |
| `<name>.policy.minimum_onebox_version` | string | — | Oldest released Onebox runner allowed to operate this environment. Expects a CalVer release such as v2026.8.0. |
| `<name>.policy.minimum_plan_schema` | string | — | Oldest executable plan schema accepted by this environment. Expects a plan schema identity such as onebox.run/executable-deploy-plan/v1alpha2. |
| `<name>.policy.require_approval` | boolean | `true` | Require a plan-bound local confirmation before mutating this environment. |
| `<name>.policy.require_migration_backup` | boolean | `false` | Require a plan-bound backup report before a release with migration risk. |
| `<name>.policy.require_migration_restore_test` | boolean | `false` | Require the backup report to state that a restore test succeeded. |
| `<name>.server` | object | — | SSH server, written as user@host or as an object with host, user, and port. Also accepts user@host. |
| `<name>.server.host` | string | — | SSH hostname or IP address. |
| `<name>.server.port` | integer | — | SSH port. The SSH default is used when omitted. |
| `<name>.server.user` | string | — | SSH user. The local SSH configuration supplies it when omitted. |

`*` marks a field that is required within its own object.