Environments¶

An agent is only as good as the computer it gets. Say the dependencies aren't installed, the database isn't up or the dev server died an hour ago. Then the output just gets weaker, and people blame the model.

hangar's environment specs (envs/*.yaml, spec 0006) describe the machine: the image, the harnesses, the credentials. This page answers how to write one. The repo can also say things about itself, in a file committed next to its code:

Environment specs¶

Specs are YAML files in envs/. They can extend each other (how extends merges):

• maps merge by key (null deletes one);
• lists replace the parent's (skills, harnesses, credentials, ...);
• the additive build inputs tools.apt and dependencies.pip/npm union;
• skills_remove: [name] drops an inherited skill.

The full design is spec 0006. A repo can describe its own steps in a committed .hangar/environment.yaml (install, start, terminals, verify). hangar builds it ahead of time, and agents start with dependencies installed and dev servers supervised (the repo's own file).

name: my-service
extends: python                    # bare + Python 3.12/uv/ruff/pytest; bare = Ubuntu + git/gh/tmux/rg
harnesses: [claude-code, codex]    # agents this env allows: claude-code, codex, pi, antigravity
default_harness: claude-code
model: { claude-code: frontier, codex: balanced }  # per harness, or one: a policy or a pinned id (harnesses.md)
tools:
  apt: [postgresql-client]
  mise: { go: "1.23" }
dependencies:
  pip: [ruff, pytest]              # installed with `uv tool install`
  npm: [pnpm]
  script: |                        # runs as the sandbox user
    curl -fsSL https://example.com/install.sh | bash
skills:
  - path: skills/repo-conventions  # copied into ~/.claude/skills and ~/.codex/skills
  - git: https://github.com/org/skills#review@main
agent_config:
  instructions: |                  # written to each allowed harness's global instructions file
    Run `make test` before you finish.
files:
  .config/foo/config.toml: "key = 1"
repo:
  url: https://github.com/me/my-service.git
  branch: main
  setup: uv sync                   # after clone
  bake: false                      # true = clone + setup at build time, for instant claims
credentials: [claude-api, codex-api, gh]  # each sandbox gets its harness's ones, plus non-agent ones (git)
secrets: { SENTRY_TOKEN: sentry }  # env var <- credential, injected at claim
mcp:                               # written in each harness's own config format at claim
  sentry: { url: "https://mcp.sentry.dev/mcp", headers: { Authorization: "Bearer ${SENTRY_TOKEN}" } }
resources: { cpus: 4, memory_gb: 8 }
warm_pool: 2                       # keep two pre-started
model_gateway: record              # model calls through hangar: the API key stays out, calls become tapes

model_gateway: record sends Claude Code's and Codex's model calls through hangar's model gateway. The sandbox gets the gateway's URL and a per-sandbox bearer instead of the API key, and each run's calls are kept as a tape. It needs HANGAR_GATEWAY_URL and an API key (subscription logins are refused).

hangar env render my-service prints the generated Dockerfile. hangar pack render codex prints a harness pack's build. When the server has no builder, hangar pack publish claude-code codex pi antigravity builds and pushes packs from your machine.

How extends merges¶

An environment spec can extends another: the shipped envs/*.yaml, a saved one, or one hangar env / create_environment cloned. The child is laid over the parent field by field:

Installing one more package never changes what the agent is told, so build inputs add up. What shapes the agent's behaviour (skills, harnesses, credentials) is the child's to state whole. To drop one inherited skill without restating the rest, name it in skills_remove:

name: python-no-conventions
extends: claude-python
skills_remove: [repo-conventions]   # by the skill's name (its `name`, else its directory's)

skills_remove applies once, to the merged list, and is not inherited. Naming a skill the environment doesn't have is an error that lists the names it has. The table is envspec.LIST_MERGE.

A repo's .hangar/environment.yaml follows it too: each field it sets replaces the environment's. Every list it may set replaces under extends as well. An experiment variant's skills and skills_remove have the same meaning (experiments).

Before #132 every list except harnesses, credentials, terminals and ports was appended. hangar env migrate-merge --dry-run lists which environments resolve differently (the safe-release upgrade).

Settings¶

REST¶

The environment, when not named, is the one a job for the repo would get.

Moved from this page¶