Autograph | Configuration and state

The env/ directory

Configuration and service state live on the host under env/. AUGR_ENV selects the active <ENV>. The whole directory is not mounted into agents; only selected service paths are.

env/ (host)

env/
├── .env.augr               # Workstation settings: environment, container CLI, Compose
│                           # command and variant, networks, corporate network block
├── .env.project            # Generated by task augr:build from env.d/; never edit it
├── <ENV>/                  # Selected by AUGR_ENV (dev in the template)
│   ├── env.d/              # Package settings and secrets: one file per package
│   │   │                   # template, copied by task augr:install, edited locally
│   │   ├── autograph.pkg.agent.env
│   │   └── autograph.pkg.proxy.env
│   ├── services/           # Service state, created by the prepare tasks
│   │   ├── dev-agent/      # Dev agent: agent/, data/, state/, .secrets/
│   │   ├── metalab-agent/  # Metalab agent: agent/, data/, state/
│   │   ├── phoenix/data/   # Phoenix traces
│   │   └── proxy/          # squid.conf, client.env, data/, logs/
│   └── cache/              # App caches: cargo-registry/, cargo-target/, pnpm-store/
├── <ENV>.snapshot/         # Copy of <ENV>/, created by task admin:snapshot
└── <ENV>.backup/env.d/     # Settings moved by task augr:uninstall; no restore task

task app:prepare, also run by task app:up, creates the app caches. Ports and paths are not settings: the Taskfiles compute them.

The root Taskfile loads the env files when a task invocation starts: after task augr:build, run the next command as a separate invocation. The build also runs the prepare tasks of installed core packages, not project packages.

Workspace and agent state

Recreating a container keeps the host-mounted files below and loses everything else: temporary files, manual installs, container configuration.

Host paths that survive recreation

<project>/
├── workspace/              # Sources, docs, delivery, agent files, dev exchange zone;
│                           # node_modules/ and build files inside survive too.
│                           # Mounted at /workspace in the dev agent (read-write)
│                           # and at /workspace/project in the metalab (read-only)
└── env/<ENV>/
    ├── services/
    │   ├── dev-agent/
    │   │   ├── agent/      # Runtime configuration, mounted at /augr/agent;
    │   │   │               # the entrypoint regenerates it at each start
    │   │   ├── data/       # OpenCode sessions and OAuth credentials;
    │   │   │               # AUGR_OPENCODE_DATA_PATH moves it (Compose v2 only)
    │   │   └── state/      # OpenCode XDG state
    │   └── metalab-agent/  # Same layout, separate data, no data path override
    └── cache/              # App caches; task app:unprepare removes them

Both agents mount the same host sources with inverted write access: the dev agent writes the workspace, the metalab writes the engine and the packages. They share the container image and Phoenix, not their OpenCode data: a login or a session in one agent is not available in the other.

Snapshot and restore

Stop app and stack containers with task app:down and task augr:down before snapshot or restore. The snapshot is a plain file copy, not a live-database backup.

terminal

task admin:snapshot          # Copy env/<ENV>/ to env/<ENV>.snapshot/;
                             # -- --force overwrites an existing snapshot
task admin:snapshot:restore  # Replace env/<ENV>/ with the snapshot after confirmation
                             # (-- --force skips it), then delete the stale env/.env.project
task admin:snapshot:purge    # Delete the snapshot after confirmation

After restore, run task augr:build, then task augr:up separately. Restart the app when needed. task admin:teardown keeps the snapshots; PURGE=1 task admin:teardown also deletes them.

Snapshots cover env/<ENV>/ only. Back up workspace/, env/.env.augr and any external OpenCode data path separately. Protect these copies: they can contain credentials.

Learn more

The security model and metalab architecture explain the access boundaries.

Transverse variables

These variables form the interface between the project, the engine, and the packages. The engine contract (engine/augr.contract.yml) declares the engine variables; the root Taskfile exports the project paths and the runtime user. Paths are host paths.

Name	Purpose	Set in
`AUGR_VERSION`	Engine version	Engine Taskfile
`AUGR_ENV`	Active environment (env/<ENV>/)	env/.env.augr
`AUGR_CONTAINER_CLI`	Container CLI for non-Compose commands	env/.env.augr
`AUGR_CONTAINER_COMPOSE_CMD`	Compose command	env/.env.augr
`AUGR_CONTAINER_COMPOSE_VARIANT`	Compose file suffix: empty or .v1	env/.env.augr
`AUGR_RUNTIME_USER_NAME`	Container user name, matching the host	Root Taskfile
`AUGR_RUNTIME_USER_UID`	Container user ID, matching the host	Root Taskfile
`AUGR_RUNTIME_USER_GID`	Container group ID, matching the host	Root Taskfile
`AUGR_PATH_ROOT`	Project root	Root Taskfile
`AUGR_PATH_WORKSPACE`	Project workspace	Root Taskfile
`AUGR_PATH_ENGINE`	Engine directory	Root Taskfile
`AUGR_PATH_DEPS`	Project packages	Root Taskfile
`AUGR_PATH_ENGINE_DEPS`	Engine packages	Root Taskfile
`AUGR_PATH_REPOS`	Bare repositories for local resolution	Root Taskfile
`AUGR_ENV_DIR`	Environment directory (env/)	Root Taskfile
`AUGR_NETWORK_GATEWAY`	Internal network of the non-agent services	env/.env.augr
`AUGR_NETWORK_AGENT`	Internal network of the dev agent	env/.env.augr
`AUGR_NETWORK_METALAB`	Internal network of the metalab agent	env/.env.augr
`AUGR_NETWORK_EGRESS`	Egress network of the proxy	env/.env.augr
`AUGR_NET_PROXY_URL`	Corporate proxy (optional)	env/.env.augr
`AUGR_NET_NO_PROXY`	Hosts reached without the corporate proxy	env/.env.augr
`AUGR_NET_CA_CERT_DIR`	Corporate CA certificates directory	env/.env.augr

Packages read these variables in their commands and Compose files, and never redefine them. AUGR_CONTAINER_COMPOSE_VARIANT is read from env/.env.augr only: a shell override does not change the selected Compose files.

Three kinds of parameters

The kind of a parameter decides where it is written and how a Taskfile reads it.

Kind	Written in	Templates	Commands and task-level sh:
Target: fixed for the machine	an env file	read the file value	read the file value
Context: set per run or CI job	the process environment only	only through a global `sh:` of the same name	read the process value
Default with override	an env file, overridden by the process	not suitable: templates ignore the override	the process value wins over the file

Templates use , commands use $X. A global sh: never sees the env files; a task-level sh: does. Validated with Task 3.51.1; the reference is engine/docs/internal/taskfile-variable-resolution.md.

Learn more

For package conventions, read the rules for package authors.