Autograph
dev

Get started

Go from zero to a running AI-augmented development environment in under 15 minutes. All you need is Git, Docker, and Task. Everything else runs inside containers.

Prerequisites

Resource requirements

Autograph runs several containers alongside your project. Here is the estimated overhead on your machine:

ComponentCPURAMNotes
Dev agent2 cores2 GBConfigurable via compose
Metalab agent2 cores2 GBOptional, only if active
Phoenix (observability)0.5 core512 MBOpenTelemetry collector + UI
West (package resolution)minimalminimalRuns only during install

Typical overhead: ~2.5 CPU cores and ~3 GB RAM with the dev agent only. Add your project containers on top. A machine with 8 cores and 16 GB RAM handles most setups comfortably.

Startup memory check

task augr:up runs a quick host check and warns if the container runtime has less than 4 GiB of memory available (8 GiB or more recommended), with tuning hints for colima and Docker Desktop.

Required tools

Git

2.x+

With submodule support. Most systems include it by default.

Install guide

Docker + Compose

Docker 20.10+ / Compose v2 recommended

Standalone docker-compose 1.28+ is an alternative with package-task limitations. Podman Compose is experimental.

Install guide

Task

3.x+

A modern task runner. Single binary, no dependencies.

Install guide

No language tooling needed

You do not need Node, Rust, pnpm, or any other language runtime on your host machine. All tooling runs inside Docker containers.

terminal
task --version
docker --version
docker compose version

The nominal setup uses Docker Compose v2. Alternative runtimes and platform-specific setup are documented under Specific contexts.

Specific context?

Configure a non-standard workstation or network before building. Each option has a focused page:

1 Clone the seed

The seed is the starter template. Clone it with submodules so the engine is resolved immediately.

terminal
git clone --recurse-submodules https://gitlab.com/opentooladd/augr/augr.seed.git my-project
cd my-project
Using WSL2?

Clone on the WSL2 Linux filesystem, not under /mnt/c/. See Windows through WSL2 for the platform-specific setup.

Forgot --recurse-submodules?

If you already cloned without --recurse-submodules, the engine/ directory will be empty. Run this from the project root to recover:

terminal
git submodule update --init

This gives you the full project structure: engine, workspace, Taskfiles, and a sample application (Nuxt 4 frontend + Rust/Axum backend).

2 First-time setup

terminal
task admin:setup

This creates the env/ directory with:

  • .env.augr : engine meta-config (environment name, container CLI, Compose command and variant, network names, corporate network block)
  • Git submodule initialization (if not done during clone)

The default configuration is ready for Docker Compose v2. Configure alternative runtimes, workstation platforms, or a corporate network from Specific contexts before continuing.

Expectedenv/ directory created with .env.augr

3 Resolve packages

terminal
task augr:install

This runs West inside a container to resolve Git-based packages into engine/deps/modules/, then collects environment templates from each package.

After this step you should see the four core packages:

  • autograph.pkg.agent : sandboxed AI agent
  • autograph.pkg.delivery : delivery tracking
  • autograph.pkg.metalab : metalab mode
  • autograph.pkg.proxy : outbound network gateway
ExpectedWest resolves packages, env templates collected into env/dev/env.d/

4 Choose LLM access

You can configure an API key now or connect interactively after the stack starts. Free hosted models may also be available directly from OpenCode. See Providers and models to choose a connection method and model without committing credentials.

5 Build the environment

terminal
task augr:build

Aggregates all per-package env files into a single env/.env.project, validates that all required variables are set, then runs any package-defined prepare steps.

Expected"Validation passed: all variables set."

6 Start the engine

terminal
task augr:up

Builds and starts the engine infrastructure (networks, Phoenix observability) and the AI agent containers (dev agent + metalab agent).

ExpectedAgent + Phoenix containers start, healthcheck reports healthy

Once the stack is running, follow Providers and models to connect a provider or select an available model.

Validate with the seed application

The seed ships with a sample app (Nuxt 4 + Rust/Axum). Run task app:start to build the app containers, install dependencies, and start dev servers. The stack must be running first. Use task app:up, task app:init, then task app:serve if you prefer separate steps to verify everything works end-to-end. This is optional - your project will define its own app:* tasks later.

7 Launch the AI agent

terminal
task augr:pkg:agent:chat

Opens an interactive session with OpenCode inside the sandboxed agent container. The agent loads its attitudes (permanent behavioral guides) and has access to skills (on-demand protocols).

ExpectedOpenCode launches with loaded attitudes and skills
Your first session

The seed ships with an E00-init-project epic designed to bootstrap your project. The agent will ask you about your stack, your goals, and your constraints - then help you adapt the seed template to your needs step by step.

Troubleshooting

task augr:build fails with "Empty required variable"

Fill in the required variables in the file named by the validation error. Provider and token can both be unset for interactive authentication. If you select an API provider, supply its required credentials in env/dev/env.d/autograph.pkg.agent.env.

Compose command missing or too old

Run task augr:engine:diagnos:docker to check the selected variant and resolved Compose configuration. Check the binary with the version commands above. Standalone v1 older than 1.28 lacks profiles support. On Debian/Ubuntu, install docker-compose (check its version), or install docker-compose-plugin from Docker's repository for v2. If an override reports "command not found", install that binary and check your PATH. Quote a command containing spaces in .env.augr, as in AUGR_CONTAINER_COMPOSE_CMD="docker compose".

Agent container not healthy

Check logs with task augr:logs - agent. Common causes: missing env variables (entrypoint fails on unresolved placeholders) or packages not resolved (task augr:install not run).

Application won't start

The app:* commands are project-specific. Check your project's Taskfile.d/apps/ for the available tasks and their requirements.

Skills not loading

  • Verify packages: ls engine/deps/modules/
  • Rebuild agent: task augr:pkg:agent:rebuild
  • Check symlinks: task augr:pkg:agent:shell then ls -la /augr/agent/skills/
Next steps

Summary

Complete sequence
# Clone
git clone --recurse-submodules https://gitlab.com/opentooladd/augr/augr.seed.git my-project
cd my-project

# Setup + install
task admin:setup
# Review env/.env.augr: Compose settings and corporate network (if needed)
task augr:install

# Configure LLM credentials
# Edit env/dev/env.d/autograph.pkg.agent.env:
#   AUGR_ADE_OPENCODE_PROVIDER_ID=anthropic
#   AUGR_ADE_OPENCODE_AUTH_TOKEN=sk-ant-...
# Or leave both unset for OAuth login below

# Build + start engine
task augr:build
task augr:up

# OAuth alternative (open the printed URL in your host browser)
# task augr:pkg:agent:connect

# Launch the agent and bootstrap your project
task augr:pkg:agent:chat
# Then prompt: 'start E00'