> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# RFC-2: Deploy Spec

## 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](/environments) 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

| Version | Date       | Changes        |
| ------- | ---------- | -------------- |
| v1.0    | 2026-10-30 | Initial 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](https://www.rfc-editor.org/rfc/rfc2119).

---

## 1. Introduction

A Deploy Spec file (`astropods.deploy.yml`) is a YAML document that sits beside `astropods.yml`. The [Blueprint Spec](/astropods-package-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:

| Field          | Type                       | Required     | Description                                         |
| -------------- | -------------------------- | ------------ | --------------------------------------------------- |
| `spec`         | string                     | **REQUIRED** | Deploy document version. MUST be `deploy/v1`.       |
| `environments` | map of name to Environment | **REQUIRED** | The environments to deploy. MUST name at least one. |

**`astropods.deploy.yml`**

```yaml title="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](/environments) 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.

| Field        | Type                    | Description                                                                                               |
| ------------ | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `branch`     | string                  | The Git branch that deploys this environment from a GitHub build (Section 5). `ast deploy -f` ignores it. |
| `cluster`    | string                  | The cluster to deploy to. Defaults to the account's default cluster.                                      |
| `interfaces` | string\[]               | The interfaces to turn on: `web`, `slack`, or `mesh`. Replaces the current set.                           |
| `public`     | Public                  | Whether the `web` or `custom` interface is open without sign-in (Section 3.1).                            |
| `variables`  | map of name to Variable | A value for each deployment variable (Section 3.2).                                                       |
| `models`     | map of name to string   | The model to use for each model entry in `astropods.yml`.                                                 |
| `schedules`  | map of name to string   | A cron expression for each scheduled job in `astropods.yml`.                                              |
| `knowledge`  | map of name to string   | The [knowledge store](/knowledge-stores) each knowledge entry in `astropods.yml` binds to.                |
| `resources`  | Resources               | The compute size of each component (Section 4).                                                           |

```yaml
production:
  models: { default: claude-sonnet-5-5 }
  schedules: { nightly_sync: "0 3 * * *" }
  knowledge: { docs: kb_docs_prod }
```

### 3.1 Public

| Field    | Type    | Description                                                          |
| -------- | ------- | -------------------------------------------------------------------- |
| `web`    | boolean | `true` opens the web chat to anyone, with no sign-in.                |
| `custom` | boolean | `true` opens the agent's own [frontend](/frontend-agents) 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.

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

### 3.2 Variables

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

| Form      | Example                                   | Meaning                                                                                              |
| --------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Literal   | `LOG_LEVEL: info`                         | The value, as written.                                                                               |
| Reference | `OPENAI_API_KEY: { ref: OPENAI_API_KEY }` | The value of the named variable in the environment or the account. See [Managing secrets](/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.

| Field          | Type                   | Sizes                                      |
| -------------- | ---------------------- | ------------------------------------------ |
| `agent`        | Compute                | The agent container.                       |
| `models`       | map of name to Compute | Each model entry in `astropods.yml`.       |
| `knowledge`    | map of name to Compute | Each knowledge entry in `astropods.yml`.   |
| `integrations` | map of name to Compute | Each integration entry in `astropods.yml`. |
| `ingestion`    | map of name to Compute | Each ingestion entry in `astropods.yml`.   |

### 4.1 Compute

| Field    | Type   | Applies to | Description                                                |
| -------- | ------ | ---------- | ---------------------------------------------------------- |
| `sizing` | string | both       | **REQUIRED.** `fixed` or `auto`.                           |
| `cpu`    | string | `fixed`    | CPU, as a Kubernetes quantity such as `"1"` or `"500m"`.   |
| `memory` | string | `fixed`    | Memory, as a Kubernetes quantity such as `2Gi` or `512Mi`. |
| `min`    | Size   | `auto`     | The smallest size the autosizer picks.                     |
| `max`    | Size   | `auto`     | The 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.

```yaml
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.

| Tool            | Environments it deploys                                                                                                       | Procedure                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `ast deploy -f` | Every environment, or those named with `--env`. It ignores `branch`.                                                          | [Deploy from a file](/cli/blueprint#deploy-from-a-file) |
| GitHub build    | Each environment whose `branch` is the connected branch, or that sets no `branch`. A commit without the file deploys nothing. | [Build and deploy from GitHub](/github-builds)          |

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`**

```yaml title="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
```