Environment Configuration

Agor’s managed environments let a repo ship a library of named variants (lean, postgres, full, …) that every branch can pick from. Variants are Handlebars-templated and get rendered into a per-branch snapshot that the Start/Stop/Nuke/Logs buttons execute against.

This page documents the data model, the template vars, deployment-local overrides, and the permission rules.

What it looks like on the card: a green env pill, one-click open, and start/stop/logs/edit icons right next to your branch’s PR badge.

Overview

Managed environments are built out of three layers, precedence low → high:

  ┌────────────────────────────────────────────────────────┐
  │ 1. .agor.yml — repo-shared, committed to git           │
  │    environment.variants.{lean,postgres,full,…}         │
  └───────────────────────────┬────────────────────────────┘
                              │ imported into repo.environment
                              ▼
  ┌────────────────────────────────────────────────────────┐
  │ 2. repo.template_overrides — DB-only, per deployment   │
  │    host.ip_address, custom.internal_registry, …        │
  └───────────────────────────┬────────────────────────────┘
                              │ deep-merged into render context
                              ▼
  ┌────────────────────────────────────────────────────────┐
  │ 3. branch rendered snapshot — plain strings          │
  │    start_command, stop_command, nuke_command,          │
  │    logs_command, health_check_url, app_url             │
  └────────────────────────────────────────────────────────┘

• Layer 1 is authored by repo maintainers and lives in .agor.yml. It’s portable: clone the repo, Import .agor.yml, done.
• Layer 2 is where each Agor deployment pins its own values (host IP, internal registry, AWS profile) without touching the shared file. Stored in the DB, never exported.
• Layer 3 is the output: a flat set of rendered strings attached to the branch. Executors run these verbatim — no templating at execute time.

Re-rendering is explicit. Editing a variant or an override does not retroactively rewrite existing branches — you hit the Render button when you want a branch to pick up changes.

Branch Environment tab — variant YAML on top, picker in the middle, rendered snapshot below. The extends: sqlite line on the postgres variant shows variants can inherit from each other.

Picking a variant — sqlite is the default for fastest boot; full mirrors production with PostgreSQL + RBAC + Unix isolation.

Template variables

Every field in a variant is a Handlebars template. The render context is built in packages/core/src/templates/handlebars-helpers.ts.

Variables

Math helpers

Math helpers are deterministic — the same branch always renders the same ports, which is what keeps parallel branches from colliding.

Broken template syntax is reported at render time, not at save time. Click Render to see the exact error with a line number.

The .agor.yml file

.agor.yml lives at the branch root ($BRANCH_PATH/.agor.yml) and is the shared, committed description of a repo’s environment variants. It’s a regular repo file: you edit it on a branch, open a PR, and it rolls out when merged.

Schema

version: 2
 
environment:
  default: lean                    # which variant new branches get
  variants:
    <variant-name>:
      description: "Human-readable one-liner"
      extends: <base-variant>      # optional, single-level only
      start:  "<shell command template>"
      stop:   "<shell command template>"
      nuke:   "<shell command template>"   # optional
      logs:   "<shell command template>"   # optional
      health: "<url template>"             # optional
      app:    "<url template>"             # optional

start, stop, nuke, and logs are rendered lifecycle fields. In the default hybrid mode they can be shell commands or explicit http:// / https:// webhooks. Webhooks are invoked with HTTP GET. health and app are always URL templates, not shell commands.

Required fields

• version: 2 at the top level.
• environment.default — must reference a variant that exists in environment.variants.
• Each variant (after extends resolution) needs at least start and stop.

nuke, logs, health, and app are optional — the corresponding UI buttons simply hide or no-op when absent.

extends (single-level only)

A variant may extend one base variant. The base variant itself must not have an extends key. Chains (full → postgres → lean) are rejected at save time with:

variant 'full' extends 'postgres', which itself extends 'lean' —
chains deeper than one level are not allowed

Resolution is a straight per-field merge: child fields win, omitted fields inherit from the base.

Worked example — Superset: lean / postgres / full

version: 2
 
environment:
  default: lean
  variants:
    lean:
      description: "SQLite-backed, single-container, fast iteration"
      start:  "docker compose -f docker-compose-light.yml -p agor-{{branch.name}} up -d"
      stop:   "docker compose -f docker-compose-light.yml -p agor-{{branch.name}} down"
      nuke:   "docker compose -f docker-compose-light.yml -p agor-{{branch.name}} down -v"
      logs:   "docker compose -f docker-compose-light.yml -p agor-{{branch.name}} logs --tail=100"
      health: "http://{{host.ip_address}}:{{add 9000 branch.unique_id}}/health"
      app:    "http://{{host.ip_address}}:{{add 5000 branch.unique_id}}"
 
    postgres:
      description: "Postgres + Redis + Celery — closer to prod"
      extends: lean                # inherits health + app from lean
      start:  "docker compose -p agor-{{branch.name}} up -d --build"
      stop:   "docker compose -p agor-{{branch.name}} down"
      nuke:   "docker compose -p agor-{{branch.name}} down -v"
      logs:   "docker compose -p agor-{{branch.name}} logs --tail=100"
 
    full:
      description: "Postgres + Redis + Celery + worker + beat"
      extends: lean                # NOT extends: postgres — chains are not allowed
      start:  "COMPOSE_PROFILES=full docker compose -p agor-{{branch.name}} up -d --build"
      stop:   "docker compose -p agor-{{branch.name}} down"
      nuke:   "docker compose -p agor-{{branch.name}} down -v"
      logs:   "docker compose -p agor-{{branch.name}} logs --tail=100"

Notice that postgres and full both extend lean (not each other) — that’s the single-level rule. Both inherit health and app from lean and override the rest.

Import / export

Two admin-only actions in the repo editor header:

Both paths go through a confirm dialog. Import is replace, not merge — a variant that exists in the DB but not in the file gets dropped.

Because the target is always the file in the currently open branch, the normal workflow is:

1. Iterate on .agor.yml on a branch.
2. Export (or hand-edit) the file.
3. Commit and PR it like any other repo change.
4. On merge, other branches can Import on their next sync.

Deployment-local overrides

template_overrides is a per-repo, per-deployment block that lives in the DB, not in .agor.yml. It’s where each Agor instance pins the concrete values that the shared variants reference (IPs, registries, profile names).

Why it exists

Superset’s upstream .agor.yml shouldn’t hard-code 10.0.1.42 as the host IP — that’s Preset’s infra, not Apache’s. Instead, Superset’s variants reference {{host.ip_address}} and Preset sets it once, per-repo, in template_overrides. The shared file stays clean; the deployment-specific values stay in the deployment.

Schema

template_overrides:
  host:
    ip_address: "10.0.1.42"        # overrides daemon config / autodetect
  custom:
    internal_registry: "registry.preset.io"
    aws_profile: "preset-dev"
    compose_profile: "preset"

The structure is a plain { host, custom } map. template_overrides is root-level and applies to all variants — there are no per-variant overrides.

Precedence

At render time the context is assembled in this order (later wins):

1. Daemon defaults (autodetected host.ip_address, etc.).
2. repo.template_overrides (deep-merged).
3. branch.custom_context (for custom.*).
4. Branch identity (branch.*, repo.*).

What it is not

⚠ template_overrides is not a secret store. It’s visible to every user with read access to the repo (admins edit, members read). Use it for infrastructure identifiers — IPs, registry hostnames, profile names — never for API keys, tokens, or passwords.

For secrets, use the per-session env-var system — scope is per-session, access is the session owner only.

The import/export parser refuses any template_overrides: key found in .agor.yml and the exporter always strips it. This is a defense-in-depth guarantee that values like host.ip_address: 10.0.1.42 cannot be accidentally committed upstream to a public repo.

Variants in the branch

Each branch has:

• environment_variant — the chosen variant name (e.g. "postgres").
• start_command, stop_command, nuke_command, logs_command, health_check_url, app_url — the rendered strings, fully substituted, no Handlebars left.

The Environment tab has two stacked editors:

Members see both editors read-only. Users with branch all permission and admins can use the Variant picker and the Render button in between them.

The Render flow

  [ Variant: postgres ▾ ]   [ Render ▸ ]

1. Pick a variant from the dropdown.
2. Click Render.
3. Agor re-evaluates variant + template_overrides and overwrites the branch snapshot.

If the snapshot has unsaved manual edits (admins only — members can’t make them), Render prompts a confirm: “Rendering will discard your local edits. Continue?”

No auto-tracking

If an admin edits a variant after a branch has rendered, the branch snapshot does not update until someone clicks Render. There is no dirty indicator, no banner, no auto-rerender. This is deliberate: branches are short-lived, and an environment that could silently change under a running stack is worse than an ossified snapshot the user refreshes when they want to.

Empty state

A repo with no variants configured shows a disabled picker and:

No environment variants configured. Ask an admin to set up commands in the repo editor above.

Permissions

Two orthogonal axes govern access: who can edit what, and who can run Start/Stop/Nuke/Logs.

Edit permissions

The reason members cannot hand-edit rendered commands: admins curate the set of commands that can run (the variants), and users with branch all permission pick from that list. This makes the variant library the effective allowlist and complements the execution-time deny-list guard.

Execution permissions

Start, Stop, Restart, Nuke, Logs, and Render controls require branch all permission or admin access. Health/status reads can remain available to users who can view the branch because they do not run the configured shell/log commands.

Migration from pre-variants Agor

No forced user action. The upgrade is silent:

Existing branches keep running against their existing rendered commands. Nothing re-renders until someone hits Render or creates a new branch.

Security notes

Two things worth internalizing before you ship a variant to the rest of the team.

1. Deny-list runs on the rendered string, at execute time

The deny-list guard (the thing that blocks destructive commands like rm -rf /) runs on the final rendered command, at execute time — not against the template, and not at save time. That means:

• A template can render to a denied command under some branch contexts and not others.
• The first visibility you have that a command is denied is when someone clicks Start / Stop / Nuke and it fails.
• Keep your templates simple — if the rendered shape of a command isn’t obvious from reading the template, add a description: to the variant so teammates know what they’re launching.

2. template_overrides is not a secret store

Restating the callout from above because it’s the single most common mistake:

• template_overrides values are visible to every user with repo access.
• Values get baked into shell strings at render time — anyone who can read the branch snapshot sees them.
• Use it for IPs, hostnames, registries, profile names. Not for API keys, tokens, or passwords.
• For secrets, use the per-session env-var system. Scope is per-session, access is limited to the session owner, and values never land in a rendered command.

3. Managed environment execution mode

Agor instances choose how lifecycle fields are handled. The default is hybrid:

# ~/.agor/config.yaml
execution:
  managed_envs_execution_mode: hybrid

In hybrid mode, lifecycle fields can be shell commands or explicit http:// / https:// webhooks. URL-shaped fields use webhook execution, so a repo can use webhooks for one action and commands for another.

Some instances are configured for webhook-managed environments:

# ~/.agor/config.yaml
execution:
  managed_envs_execution_mode: webhook-only

In webhook-only mode, rendered start, stop, nuke, and logs fields must render to explicit http:// or https:// URLs. Agor sends a GET request to the URL.

environment:
  default: remote
  variants:
    remote:
      start: "https://orchestrator.example.com/agor/start?branch={{branch.name}}"
      stop:  "https://orchestrator.example.com/agor/stop?branch={{branch.name}}"
      logs:  "https://orchestrator.example.com/agor/logs?branch={{branch.name}}"
      health: "https://apps.example.com/{{branch.name}}/health"
      app:    "https://apps.example.com/{{branch.name}}"

V1 webhooks are intentionally simple: GET only, no custom headers, no request body, no signing, and redirects are not followed. V1 webhook targets must be public HTTP(S) destinations; localhost, private/link-local ranges, and URL credentials are rejected. Use a trusted orchestration service, and avoid secrets in query strings because rendered branch snapshots and infrastructure logs may expose them.

See also

• Containerized execution — running the rendered commands inside isolated containers.
• Multiplayer and Unix isolation — how RBAC and Unix user modes gate who can Start / Render / edit env config.
• Template helper source: packages/core/src/templates/handlebars-helpers.ts
• .agor.yml parser source: packages/core/src/config/agor-yml.ts