Skip to navigation

RFC-2: Deploy Spec

Declarative YAML format for where a blueprint runs
View as Markdown

Abstract

The Deploy Spec defines a declarative YAML format for where a blueprint runs and how each of its deployments is configured. One file declares every environment a blueprint deploys to: its cluster, interfaces, variables, models, schedules, knowledge bindings, and compute. The CLI deploys the file with ast deploy -f, and a connected GitHub repository deploys it after each build.

Changelog

VersionDateChanges
v1.02026-10-30Initial draft.

Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.


1. Introduction

A Deploy Spec file (astropods.deploy.yml) is a YAML document that sits beside astropods.yml. The Blueprint Spec describes how to build the agent. The Deploy Spec describes where it runs.

The file deploys the blueprint named in the astropods.yml in the same directory, so it names no blueprint itself. Each environment in the file maps to one deployment of that blueprint.

The file is the reviewed, versioned record of deploy settings. Commit it with the code, and every deploy from it is repeatable.

The spec does not cover access grants. A first deploy gets the default grants, and the agent’s Access tab changes them.


2. Top-Level Structure

A conforming document MUST contain the following top-level fields:

FieldTypeRequiredDescription
specstringREQUIREDDeploy document version. MUST be deploy/v1.
environmentsmap of name to EnvironmentREQUIREDThe environments to deploy. MUST name at least one.
astropods.deploy.yml
spec: deploy/v1
environments:
production:
branch: main
cluster: us-east-1
interfaces: [web, slack]
variables:
LOG_LEVEL: info
OPENAI_API_KEY: { ref: OPENAI_API_KEY }
staging: {}

An environment name is the name of an environment in the account. If the environment doesn’t exist, the deploy creates it. An empty entry (staging: {}) deploys with the current values, or the defaults on a first deploy.


3. Environment

Every field in an environment is OPTIONAL. A field the file leaves out keeps the deployment’s current value on a redeploy, and the default on a first deploy.

FieldTypeDescription
branchstringThe Git branch that deploys this environment from a GitHub build (Section 5). ast deploy -f ignores it.
clusterstringThe cluster to deploy to. Defaults to the account’s default cluster.
interfacesstring[]The interfaces to turn on: web, slack, or mesh. Replaces the current set.
publicPublicWhether the web or custom interface is open without sign-in (Section 3.1).
variablesmap of name to VariableA value for each deployment variable (Section 3.2).
modelsmap of name to stringThe model to use for each model entry in astropods.yml.
schedulesmap of name to stringA cron expression for each scheduled job in astropods.yml.
knowledgemap of name to stringThe knowledge store each knowledge entry in astropods.yml binds to.
resourcesResourcesThe compute size of each component (Section 4).
production:
models: { default: claude-sonnet-5-5 }
schedules: { nightly_sync: "0 3 * * *" }
knowledge: { docs: kb_docs_prod }

3.1 Public

FieldTypeDescription
webbooleantrue opens the web chat to anyone, with no sign-in.
custombooleantrue opens the agent’s own frontend to anyone.

public MUST appear only in an environment that also sets interfaces.

A public web interface has no signed-in user, so its access becomes anyone. A redeploy that makes web public replaces the web grants with anyone and records the change in the audit log.

production:
interfaces: [web]
public: { web: true }

3.2 Variables

A variable is either a literal value or a reference to a secret:

FormExampleMeaning
LiteralLOG_LEVEL: infoThe value, as written.
ReferenceOPENAI_API_KEY: { ref: OPENAI_API_KEY }The value of the named variable in the environment or the account. See Managing secrets.

A variable the blueprint marks as secret MUST use ref. The deploy refuses a literal value for it, so a secret never lands in the file.


4. Resources

resources sizes each component. Each entry MUST set sizing, so the file always states who sizes the component.

FieldTypeSizes
agentComputeThe agent container.
modelsmap of name to ComputeEach model entry in astropods.yml.
knowledgemap of name to ComputeEach knowledge entry in astropods.yml.
integrationsmap of name to ComputeEach integration entry in astropods.yml.
ingestionmap of name to ComputeEach ingestion entry in astropods.yml.

4.1 Compute

FieldTypeApplies toDescription
sizingstringbothREQUIRED. fixed or auto.
cpustringfixedCPU, as a Kubernetes quantity such as "1" or "500m".
memorystringfixedMemory, as a Kubernetes quantity such as 2Gi or 512Mi.
minSizeautoThe smallest size the autosizer picks.
maxSizeautoThe largest size the autosizer picks.

A Size has cpu and memory, with the same format as above.

  • sizing: fixed sets the size and turns the autosizer off. A redeploy keeps that size instead of the one the autosizer chose.
  • sizing: auto lets the platform size the component, within optional min and max bounds.
resources:
agent: { sizing: fixed, cpu: "1", memory: 2Gi }
models:
default: { sizing: auto, max: { cpu: "2", memory: 4Gi } }

5. Deploying

Two tools deploy the file. Both MUST deploy only the environments described here, and MUST leave out of the request every field an environment omits.

ToolEnvironments it deploysProcedure
ast deploy -fEvery environment, or those named with --env. It ignores branch.Deploy from a file
GitHub buildEach environment whose branch is the connected branch, or that sets no branch. A commit without the file deploys nothing.Build and deploy from GitHub

A GitHub build reads astropods.deploy.yml from the directory that holds astropods.yml, at the pushed commit.


6. Validation Rules

Implementations MUST enforce the following validation rules:

  1. spec MUST equal deploy/v1.
  2. environments MUST name at least one environment.
  3. An environment name MUST be 1 to 64 characters, with no leading or trailing spaces.
  4. branch MUST NOT have leading or trailing spaces.
  5. Each entry in interfaces MUST be web, slack, or mesh.
  6. public MUST NOT be set unless interfaces is set in the same environment.
  7. Each variable MUST be a non-empty value or { ref: NAME }, where NAME is not empty. A ref mapping MUST contain no other key.
  8. A secret variable MUST use ref. This rule is checked at deploy time against the blueprint’s variables.
  9. Each resources entry MUST set sizing to fixed or auto.
  10. sizing: fixed MUST set cpu or memory, and MUST NOT set min or max.
  11. sizing: auto MUST NOT set cpu or memory. A min or max it sets MUST set cpu or memory.
  12. The file MUST contain exactly one YAML document. Unknown fields anywhere in the document are rejected.
  13. The file MUST NOT exceed 64 KiB.

Validation runs offline. It does not check that a cluster, variable, model, or knowledge store exists; the deploy reports those.


Appendix A: Complete Example

astropods.deploy.yml
spec: deploy/v1
environments:
production:
branch: main
cluster: us-east-1
interfaces: [web, slack]
public: { web: false }
variables:
LOG_LEVEL: info
OPENAI_API_KEY: { ref: OPENAI_API_KEY }
models: { default: claude-sonnet-5-5 }
schedules: { nightly_sync: "0 3 * * *" }
knowledge: { docs: kb_docs_prod }
resources:
agent: { sizing: fixed, cpu: "1", memory: 2Gi }
models:
default: { sizing: auto, max: { cpu: "2", memory: 4Gi } }
staging:
variables:
LOG_LEVEL: debug