Open Envelope wants to be the Dockerfile for AI agent teams

The multi-agent system is the deployment pattern that everyone talks about and nobody has standardized. A dozen frameworks exist — LangGraph, CrewAI, AutoGen, Claude Code’s dynamic workflows — but each defines an agent team in its own bespoke format. Move a team definition from one runtime to another and you rewrite it from scratch.

Ashconway shipped a fix to Hacker News on May 31: Open Envelope, an open JSON Schema for defining AI agent teams. The schema covers agent roles, supervisor-subagent hierarchies, human-in-the-loop gates, pipelines, schedules, and secrets injection. It lives at schema.openenvelope.org, is registered in SchemaStore (so VS Code offers autocomplete on .envelope.json files), and is published on npm as @openenvelope/schema. The license is Apache 2.0.

The pitch is familiar to anyone who remembers the containerization wars. “Define a team once, any compatible runtime can execute it,” the README states. Open Envelope draws the analogy explicitly: Dockerfiles describe a container without being tied to a specific host. Envelope wants to do the same for agent teams.

What the schema actually specifies

The schema at team-v1.json defines a team as a collection of agents, each with a role, a system prompt, a model binding, and an access policy. The access policy is the most interesting detail. It lets you declare exactly which hosts each agent can call. The runtime enforces this at the network level, not in the prompt. That is a meaningful architectural choice. Most agent frameworks rely on prompt-based instructions to keep an agent from calling the wrong API. Open Envelope makes it a structural constraint.

The spec also includes supervisor-subagent hierarchies, human-in-the-loop gates (GateTypes for approval workflows), pipelines for sequential agent execution, schedules for recurring runs, and a variables system for environment-specific secrets. The schema is registered at https://schema.openenvelope.org/team/v1.json and follows semantic versioning with a backwards-compatibility guarantee within major versions.

A managed runtime exists at openenvelope.org, but the schema is designed to be implementable by anyone. The GitHub repository includes validation tooling via AJV and TypeScript bindings.

The hard part is not the schema

The HN thread surfaced the real challenge immediately. User nostrebored, who described building a similar system internally, raised a structural critique: declarative approaches require validation to live at a synthesis layer, while imperative approaches that compile down to declarative configs give you the best of both worlds. They compared it to the Terraform ecosystem, where most practitioners prefer CDK or Pulumi over raw HCL.

The critique is precise. A schema defines what a valid team looks like. It does not define how that team executes. The gap between validation and orchestration is where every agent runtime differentiates itself. LangGraph offers state machines with conditional edges. CrewAI offers role-based delegation with task pipelines. Claude Code offers dynamic workflows that the model constructs at runtime. None of these can be expressed purely in a schema.

Open Envelope’s answer is that the schema is the interface, not the implementation. Any runtime that understands the schema can execute the team definition however it wants. That is the Docker analogy again. But Docker succeeded because the runtime (containerd, runc) and the image format were developed together by the same organization. Open Envelope ships the schema first and hopes runtimes follow.

Access policy as a differentiator

The access policy mechanism is worth watching. Most agent security today is prompt-based: you tell the agent not to call certain endpoints and hope it listens. Open Envelope enforces access at the network level. The runtime intercepts outbound calls and blocks those not in the declared policy. This is closer to how Kubernetes NetworkPolicies work than how current agent frameworks handle security.

If the Open Envelope runtime or a compatible implementation enforces this correctly, it solves a real problem. Enterprise deployments of multi-agent systems are stalled partly because security teams cannot audit what an agent might call. A declarative access policy that the runtime enforces is auditable. You can check a .envelope.json file into version control and review it like any other infrastructure configuration.

The ecosystem trap

Open Envelope faces the same chicken-and-egg problem as every open standard. The schema is useful only if runtimes implement it. Runtimes implement it only if teams use it. Teams use it only if their framework of choice supports it.

The HN commenter zatkin raised the obvious counterpoint: Claude Code already wants to own this problem with its own dynamic workflow system. Anthropic has no incentive to implement an open schema. Neither does Microsoft with AutoGen, or Google with its agent framework. The incumbents benefit from lock-in.

Open Envelope’s best path is the long tail. Small teams building custom multi-agent systems who want portability without vendor commitment. Teams that deploy across multiple runtimes and need a single source of truth. The schema is Apache 2.0, which means anyone can fork it, extend it, or ignore it. The question is whether the ecosystem coalesces around a single representation or fragments further.

What to watch

The next six months will tell the story. Watch for runtime implementations that are not the Open Envelope managed runtime. Watch for pull requests that add support for conditional branching, plan-solving, or dynamic agent creation — features that the current schema does not handle and that nostrebored correctly identified as gaps. Watch for adoption in open-source agent frameworks that want to offer a portable export format.

Open Envelope has done the hard work of writing down what an agent team looks like. The harder work is convincing the rest of the industry to agree.