AegisTrace is a verifiable runtime for durable AI workflows. It compiles readable YAML into digest-sealed artifacts, rejects unsafe workflow graphs before execution, records every state transition in a hash-chained journal, and produces independently verifiable Merkle and Ed25519 proofs.

The runtime treats model and tool calls as effects. Live runs invoke configured providers; replay reads recorded results and never contacts a provider. This gives operators a stable audit record and developers a reproducible debugging path without pretending that external models are deterministic.

Status

AegisTrace is an early, working release. The local runtime, compiler, verifier, journal, replay, checkpoints, proof system, capability tokens, HTTP model adapters, MCP adapter, and CLI are implemented. Distributed scheduling, database backends, and OpenTelemetry export are roadmap items.

How it works

Source is compiled with unknown-field rejection, statically verified, and sealed into a digest-locked artifact. At run time the runtime drives every external effect through the provider boundary, writes each transition into the hash-chained journal, and can produce a signed Merkle proof. Replay reconstructs the run from the journal and never reaches a provider.

Features

• Strict YAML compiler with unknown-field rejection
• SHA-256 sealed, portable JSON artifacts
• Static validation of graph reachability, cycles, budgets, references, and tool permissions
• Budgeted execution with model, tool, approval, checkpoint, and emit steps
• Atomic local checkpoints for crash-safe state capture
• Append-only JSONL journal with a SHA-256 hash chain
• Offline replay with chain verification
• Merkle inclusion proofs signed with Ed25519
• Short-lived Ed25519 capability tokens with scoped permissions
• OpenAI-compatible, Anthropic, Gemini, Ollama, MCP, and deterministic local adapters
• Zero Python runtime dependency

What AegisTrace proves

AegisTrace separates claims it can verify from properties that remain outside the runtime boundary.

AegisTrace does not certify that a model response is correct, that an allowed tool is safe, or that a compromised host is trustworthy. Those boundaries are explicit so attestations remain meaningful.

Failure behavior

The runtime fails closed at each boundary:

• Unknown YAML fields stop compilation.
• Modified or unknown artifact formats stop loading.
• Missing inputs and prior-step outputs stop the affected step.
• Provider response bodies larger than 8 MiB are rejected.
• Workflow deadlines cancel in-flight HTTP requests.
• Exhausted step, tool, or token budgets terminate the run.
• Missing approval prevents guarded execution.
• Journal-chain divergence prevents replay and proof creation.
• Invalid signatures, roots, paths, scopes, and expirations prevent verification.

Provider errors may follow an explicitly verified on_error edge. Without that edge, the journal records a terminal run.failed event.

Operational model

For local development, one aegis process owns the workflow, provider registry, journal writer, and checkpoint directory. This keeps the trusted execution path small and makes the binary easy to inspect and deploy.

For production use, run AegisTrace with a dedicated service identity, separate credentials by provider, keep MCP permissions narrow, encrypt journals and checkpoints at rest, and move attestation keys into a managed signer. The artifact and proof formats do not depend on a particular storage platform, so future distributed workers can preserve the same verification model.

A typical promotion flow is:

source review -> compile -> verify -> sign/release artifact
                                      |
                                      v
                               execute with policy
                                      |
                         journal + checkpoints + proof
                                      |
                                      v
                              audit / replay / CI

Install

AegisTrace requires Go 1.22 or newer.

go install github.com/cyptnpassira/AegisTrace/cmd/aegis@latest

From a checkout:

go build -o aegis ./cmd/aegis
go test ./...

Quick start

Compile and verify the example:

aegis compile examples/echo-agent.yaml -o echo.aegis
aegis verify echo.aegis

Run it and retain the audit journal:

aegis run echo.aegis \
  --input '{"message":"Investigate checkout latency"}' \
  --journal run.atlog

Replay and inspect without invoking tools:

aegis replay run.atlog
aegis inspect run.atlog --event 2

Create a signed inclusion proof:

aegis keygen -o signing-key.json
aegis prove run.atlog --event 2 --key signing-key.json -o event.proof.json
aegis verify-proof event.proof.json

Workflow example

name: issue-triage
version: "1"
entry: classify
budget:
  max_steps: 8
  max_tool_calls: 1
  max_tokens: 1000
  timeout: 30s
permissions:
  - tool: ticket.create
steps:
  - id: classify
    kind: model
    provider: echo
    input:
      prompt: ${input.message}
  - id: save
    kind: checkpoint
  - id: create
    kind: tool
    provider: echo
    action: ticket.create
    requires_approval: true
    input:
      classification: ${steps.classify}
  - id: result
    kind: emit
    input:
      ticket: ${steps.create}

Blank next fields are normalized to the following step. Explicit next and on_error edges are supported. Workflows must form a finite DAG; unbounded loops are rejected.

Providers

echo is always available and makes no network calls. Other adapters are enabled only when their endpoint environment variable is set.

Provider responses are capped at 8 MiB. HTTP clients use request deadlines inherited from the workflow budget.

Security model

A valid artifact proves structural properties; it does not prove that a model response is truthful or a permitted tool is harmless. Provider credentials remain process-local and are never inserted by AegisTrace into workflow artifacts. Journal files can contain sensitive inputs and outputs and are created with owner-only permissions where supported.

Read SECURITY.md and THREAT_MODEL.md before production use.

Formats and compatibility

• Workflow source: YAML
• Artifact: aegis/v1 JSON with a SHA-256 workflow digest
• Journal: newline-delimited JSON with per-event chaining
• Proof: aegis-proof/v1 JSON
• Capability: signed compact token with aegis-cap/v1 domain separation
• Checkpoint: aegis-checkpoint/v1 JSON

Versioned formats are documented in SPECIFICATION.md. Unknown artifact fields are rejected to prevent ambiguous interpretation.

Repository layout

cmd/aegis/      command-line interface
workflow/       portable schema and artifact seal
compiler/       strict source compiler
verifier/       static admission checks
runtime/        budgeted execution and replay
journal/        tamper-evident event log
proof/          Merkle and Ed25519 attestations
policy/         scoped capability tokens
provider/       model, MCP, and local adapters
checkpoint/     atomic state persistence
examples/       runnable workflows

Design principles

1. Verify before execution.
2. Put every external effect behind a provider boundary.
3. Record results, not secrets required to obtain them.
4. Make tampering detectable with standard cryptography.
5. Keep formats small, explicit, and versioned.
6. Prefer reproducibility and clear failure over hidden recovery.

Development

go fmt ./...
go vet ./...
go test -race ./...
go build ./cmd/aegis

Every source file must remain below 500 lines. Contributions should add focused packages rather than expanding central files indefinitely.

License

Apache License 2.0. See LICENSE.