Architecture overview

What is autograph?

autograph is a minimalist engine that assembles an AI-augmented development environment from composable packages. It provides the orchestration layer (dependency resolution, security sandboxing, lifecycle tasks, diagnostics) while packages provide the substance: a sandboxed AI agent, delivery tracking, knowledge curation, and more.

You don't install autograph globally. You embed it as a Git submodule in a project that follows the seed structure. The engine is frozen infrastructure; your project is the mutable workspace.

Engine + Packages + Seed

The architecture has three layers that compose into a working project.

Runtime topology

At runtime, containers are wired into isolated networks. A dedicated proxy (pkg.proxy) is the single outbound gateway: every agent routes its internet traffic through it. Agent networks are internal (no direct internet), so if the proxy is down, agents have zero egress. The seed app containers use the same proxy on its gateway network.

• The agents stay on separate internal networks. Front, playground, and back join the internal gateway network (AUGR_NETWORK_GATEWAY) and load the proxy's client.env settings.
• augr-host-only lets Phoenix and the app containers publish ports to the host, without internet access (IP masquerading is disabled).
• augr-host-internet is a separate, temporary direct-internet network through host NAT. No container joins it by default.
• West runs separately in infra/docker/west.compose.yaml (or its v1 variant), on Docker's default bridge, not on the agents' or gateway networks. It reads the corporate network block directly because it runs before the stack proxy exists.

The workstation's corporate block lives in env/.env.augr (AUGR_NET_*). Squid reads it for its upstream, while West and image builds use it directly. CA trust belongs to each image that makes TLS connections, not to squid, which only tunnels HTTPS.

OAuth login via task augr:pkg:agent:connect temporarily uses a host-network container for the browser's loopback callback. Its proxy is augr-proxy's host-loopback endpoint (127.0.0.1:13128 by default), not the corporate proxy. The regular agent keeps its isolated network.

Project layout

Every autograph project follows this directory structure. The layout encodes the security model: where a file lives determines its access level.

my-project/
├── Taskfile.yaml              # Single operator entry point
├── Taskfile.d/                # Task definitions (admin, augr, apps)
├── exchange.lab.tmp/          # Metalab exchange zone (L2 proposals)
├── engine/                    # autograph engine (git submodule, L2)
│   ├── augr.contract.yml      # Machine-readable contract
│   ├── Taskfile.yaml          # Engine tasks
│   ├── deps/
│   │   ├── manifest/west.yml  # Declares core packages
│   │   └── modules/           # Resolved packages (West)
│   ├── infra/                 # Engine infrastructure (West, Phoenix)
│   ├── scripts/               # Observation (diagnos), git guards, snapshots
│   └── docs/                  # Glossary, ADRs
├── deps/                      # Project packages (West)
├── env/                       # Secrets and config (gitignored, L3)
│   ├── .env.augr              # Engine meta-config
│   └── dev/env.d/             # Per-package env files
└── workspace/                 # Agent working area (L1, read-write)
    ├── AGENTS.md              # Agent operating manual
    ├── agent/                 # Project skills
    ├── src/                   # Application source code
    ├── infra/                 # App compose + Dockerfiles
    ├── delivery/              # Work tracking (epics, tickets)
    ├── exchange.dev.tmp/      # Agent exchange zone (proposals, canvas)
    └── env.template/          # Env templates (committed, no secrets)

Package lifecycle

Packages are the unit of extension. Every capability follows the same contract and lifecycle.

Package manifest

Each package declares an augr.pkg.yml manifest:

name: autograph.pkg.agent
version: 0.1.0
description: Sandboxed AI agent (OpenCode) with defense-in-depth

contract:
  engine_version: '>=0.1.0'

compose: infra/compose.yaml
taskfile: Taskfile.yaml
skills: agent/skills/
env_template: env.template/.env

Resolution and lifecycle

Packages are resolved by West (Zephyr's meta-tool for Git-based dependency management): the core packages, from the engine manifest, into engine/deps/modules/; the project packages, from the project manifest, into deps/modules/, by hand for now (see Create a package).

Shared agent image

The dev agent and the metalab agent run from the same Docker image, on independent networks and runtime state. Two agents exist on purpose: when you rebuild or test changes on one, the other keeps a working AI available - you never lose your assistant mid-task.

Learn more

The engine's design is fully documented through Architecture Decision Records. Each ADR captures the context, options considered, decision made, and consequences.