Envelope

Deploying from a Spec

Your PM designed AI agents in Envelope and exported the .envelope.json. This guide covers your options for turning that spec into running agents.

Your three paths

| Path | Best for | Setup time | |------|----------|-----------| | MCP | Run from Claude or ChatGPT, no infrastructure | 2 minutes | | Envelope API | Programmatic install, CI/CD, or custom orchestration | 30 minutes | | Bring your own runtime | Use the spec as a blueprint, run agents in your own stack | Your call |

Path 1 — MCP (zero-config)

Add Envelope as a connector in Claude.ai or ChatGPT. Your workspace becomes available as tools in any conversation — no servers, no config.

Server URL: https://mcp.openenvelope.org/api/mcp
  1. Paste the URL into your AI tool's connector settings
  2. Sign in with OAuth — your workspace appears as tools
  3. Run list_installs to see your installed agents

→ Connect to Claude.ai
→ Connect to ChatGPT

Credentials (API keys, secrets) are stored in your Envelope org vault and applied automatically at run time.

Path 2 — Envelope API

The REST API gives you full programmatic control.

Authenticate:

curl -H "Authorization: Bearer $ENVELOPE_API_KEY" \
  https://openenvelope.org/api/templates

Install the agents:

curl -X POST https://openenvelope.org/api/installs \
  -H "Authorization: Bearer $ENVELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_abc123",
    "name": "Support Triage (Prod)"
  }'

Pass required secrets at install time:

Check requiredSecrets in the spec, then provide them:

curl -X POST https://openenvelope.org/api/installs/{installId}/secrets \
  -H "Authorization: Bearer $ENVELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ZENDESK_API_KEY": "...",
    "SUPPORT_EMAIL": "[email protected]"
  }'

Trigger a run:

curl -X POST https://openenvelope.org/api/installs/{installId}/run \
  -H "Authorization: Bearer $ENVELOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Ticket #4821: login not working after password reset"}'

→ Full API reference at /api-docs

Path 3 — Bring your own runtime

Use the .envelope.json as a blueprint and implement the agents in your own stack (LangGraph, CrewAI, LlamaIndex, plain API calls, etc.).

What you need from the spec:

| Spec field | How you use it | |-----------|---------------| | agents[].prompt | System prompt for each LLM call | | agents[].capabilities | Determines which tools each agent needs access to | | agents[].reportsTo | Defines the routing logic between agents | | requiredSecrets | The credentials to provision before running | | requiredVariables | Non-secret config to inject |

The spec doesn't dictate which LLM or framework to use — those are runtime decisions. The Envelope schema describes what the agents do; your runtime decides how.

Handling required credentials

Every spec lists its credential requirements in requiredSecrets. Before the agents can run, each of these must be provisioned.

In Envelope: Store credentials in your org vault (Settings → Credentials). They're applied automatically on install.

In your own runtime: Pass them as environment variables or inject them via your secrets manager.

Never put credentials in the spec file itself — the spec is designed to be committed to Git safely.

→ Tool credentials & permissions

Verifying the spec first

Before deploying, validate the spec against the schema:

npx @openenvelope/schema validate ./your-team.envelope.json

This catches structural errors before they surface at runtime.

→ Reading an Envelope spec

‹ All guidesDocs ›