RFC-1: Astropods Spec

Abstract

The Astropods Spec defines a declarative YAML format for describing the topology of an AI agent: its container, model dependencies, knowledge stores, integrations, and data ingestion pipelines. The spec is consumed by build tools and deployment servers; it intentionally excludes runtime, orchestration, and deployment-environment concerns. At deploy time, the platform combines this spec with runtime configuration (credentials, interfaces, schedules) to produce a resolved deployment spec, which is then translated into infrastructure manifests.

Changelog

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

An AstroAI Spec file (astropods.yml) is a YAML document that declares:

• The agent’s container image (pre-built or build-from-source).
• How users reach the agent: its own web frontend, messaging adapters (Slack, web chat), or both.
• Components the agent depends on (models, knowledge stores, and integrations), each supplied by either a platform-managed provider or a user-managed container.
• Custom providers for external API services that require credential injection.
• Data ingestion pipelines with trigger semantics.
• Local development overrides.

A central concept is provider binding. Components that an agent depends on (models, knowledge stores, and integrations) are each declared as either a provider reference or a container definition:

• A provider is a named, platform-known service (e.g. ollama, anthropic, qdrant). The platform resolves each provider to one of two kinds:
  • Self-hosted: the platform deploys and manages a container on the agent’s behalf.
  • Cloud: the platform injects credentials for an external API.
• A container gives the user full control over the image, port, and configuration.

This design lets authors mix managed and custom components freely within a single spec.

The spec does not cover: resource limits (CPU/memory), observability, rate limits, budgets, security policies, or deployment region. These are deployment-time concerns configured separately.

The document format is YAML. Implementations MUST accept files named astropods.yml.

2. Top-Level Structure

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

Map keys serve as entry names and are used in credential injection (see Section 8).

2.1 Meta

3. Agent

The agent object defines the agent’s primary service: its container image or build configuration.

An agent entry MUST specify exactly one of image or build. Providing both or neither is invalid.

3.1 BuildConfig

BuildSecret

3.2 Healthcheck

Applies to the agent definition and to any ContainerConfig.healthcheck in component sections.

Implementations SHOULD support both test (exec-based) and path (HTTP-based) health checks. When path is provided, the implementation SHOULD generate an equivalent test command.

3.3 Interfaces

The interfaces object declares how users reach the agent. Both fields are booleans indicating whether the agent has the capability. Deployment-time configuration (which messaging adapters to enable, domain routing, etc.) belongs in the deployment spec or dev.interfaces.

Omitting interfaces entirely preserves backward compatibility; the platform defaults to messaging enabled.

interfaces MUST be declared under the agent key. A common mistake is placing it at the top level of the spec, which the platform ignores.

When frontend is true, the agent container MUST serve HTTP on port 80 in production (see Validation Rule 15). Use dev.interfaces.frontend.port to specify a different port for local development; the platform proxies that port to port 80.

1
# Correct — interfaces nested under agent
2
agent:
3
  build:
4
    context: .
5
    dockerfile: Dockerfile
6
  interfaces:
7
    frontend: true
8
    messaging: false
9
10
# Agent serves its own UI and supports messaging
11
agent:
12
  interfaces:
13
    frontend: true
14
    messaging: true
15
16
# Classic conversational agent (equivalent to omitting interfaces)
17
agent:
18
  interfaces:
19
    messaging: true

4. Component Sections: Models, Knowledge, Integrations

Models, knowledge stores, and integrations share a unified provider binding scheme. Each entry operates in exactly one of two modes:

• Provider mode: the entry specifies a provider string. The platform resolves this to either a self-hosted provider (deploys a container from its registry) or a cloud provider (injects credentials).
• Container mode: the entry specifies a container object. The user manages the image, port, and configuration.

These modes are mutually exclusive: an entry MUST specify exactly one of provider or container. Providing both or neither is invalid.

4.1 Models

The models section declares AI models the agent consumes: LLMs (e.g. Claude, GPT, Llama), embedding models, or any model served behind an inference API. Each entry in the models map:

4.2 Knowledge

Each entry in the knowledge map:

When persistent is true, the platform SHOULD provision durable storage for the entry. For provider-mode entries, the mount path is resolved from the provider registry. For container-mode entries, the volume field on ContainerConfig specifies the mount path (e.g. /var/lib/postgresql/data for Postgres).

inputs applies to both provider-mode and container-mode entries. They are injected into the knowledge container at runtime — not into the agent.

The built-in postgres provider manages its own credentials automatically: the platform generates a random password and a platform-managed user, then injects POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB into the agent container via secrets. No inputs are needed on the knowledge entry:

1
knowledge:
2
  db:
3
    provider: postgres
4
    persistent: true

In your agent, always read all five env vars — never hardcode user or password:

1
const pool = new Pool({
2
  host: process.env.POSTGRES_HOST ?? 'localhost',
3
  port: parseInt(process.env.POSTGRES_PORT ?? '5432'),
4
  database: process.env.POSTGRES_DB ?? 'postgres',
5
  user: process.env.POSTGRES_USER ?? 'postgres',
6
  password: process.env.POSTGRES_PASSWORD ?? 'postgres',
7
});

For custom containers that need configuration, use inputs to pass values into the container:

secret: true and ast project start: Inputs marked secret: true are stored securely and never logged. However, because they have no plaintext default, they require ast project configure to be run before ast project start can start the container. If you need the container to start immediately in local dev without a manual configure step, use a non-secret input with a default value instead.

4.3 Integrations

The integrations section declares services the agent invokes to perform actions or retrieve data. Integrations can be HTTP APIs, MCP (Model Context Protocol) servers, or any service exposed over a network port. Each entry in the integrations map:

For external API services that need credentials but no platform-managed container, define a custom provider in the providers section (see Section 5) instead.

4.4 ContainerConfig

Used by container-mode entries and by ingestion containers.

A ContainerConfig SHOULD specify at least one of image or build.

Configuring Containers with Inputs

Use inputs to declare values that the container needs at runtime. Each input is prompted via ast configure at deploy time and injected as an environment variable into the container. Values marked secret: true are stored securely and never logged.

1
knowledge:
2
  db:
3
    container:
4
      image: postgres:17
5
      port: 5432
6
      volume: /var/lib/postgresql/data
7
    persistent: true
8
    inputs:
9
      - name: POSTGRES_DB
10
        datatype: string
11
        default: my_database
12
        description: Database name
13
      - name: POSTGRES_PASSWORD
14
        datatype: string
15
        secret: true
16
        description: Database superuser password

GPUConfig

4.5 Input

An Input declares a user-supplied value that the platform prompts for at deploy time and injects as an environment variable into the target container. The name is used directly as the env var key. See Section 8.4 for injection targets.

The datatype field controls validation and type coercion applied before injection. secret is orthogonal to datatype and controls storage and logging: when true, the platform stores the value securely and never logs it. The display-as field controls UI rendering: short-text renders a single-line field, long-text a multi-line field, and select a dropdown using options.

5. Custom Providers

The providers section extends the platform’s built-in provider registry with user-defined entries. A custom provider declares the variables it requires so the platform can prompt for them at deploy time. Custom providers behave like cloud providers (§8.1): they inject credentials into the agent, not connection details.

Each variable’s name is a suffix. The full env var key is formed as {UPPER(provider)}_{varName}, following the same rule as §8.1. Duplicate-entry handling also mirrors §8.1: when multiple entries reference the same custom provider, each entry gets a qualified key; the primary entry also gets the bare key.

Custom providers can be referenced by name from the models, knowledge, and integrations sections, just like built-in providers. The scope field controls which sections are allowed to reference the provider; the platform MUST reject references from sections not listed in scope.

6. Ingestion

The ingestion section declares data ingestion pipelines. Each entry is a container that runs on a trigger.

IngestionTrigger

Trigger type semantics:

• schedule: runs on a cron schedule. The cron expression is supplied at deploy time.
• startup: runs once automatically at deploy time.
• manual: runs on demand via API invocation.
• webhook: deploys as a long-running service that receives incoming HTTP requests. The container SHOULD declare a port when using this trigger type.

7. Dev

The dev section provides local development overrides consumed by astro dev. These fields are deployment concerns that do not belong in the normative agent topology.

DevInterfaces

DevFrontend

DevMessaging

SlackAdapterConfig

DevOverrides

8. Environment Variable Injection Model

The platform automatically injects environment variables into the agent to wire it to its dependencies. The injection model differs by entry mode: cloud providers inject credentials, self-hosted providers inject connection details, and container-mode entries inject generic connection details.

8.1 Cloud Provider Credentials

Cloud providers (in models, knowledge, integrations) require user-provided credentials at deploy time. The env var key is derived from the provider name, not the entry name:

Single entry for a provider:

{UPPER(provider)}_{suffix}

Example: one anthropic model entry → ANTHROPIC_API_KEY.

Multiple entries for the same provider (duplicate handling):

Each entry gets a name-qualified key:

{UPPER(provider)}_{UPPER(entry_name)}_{suffix}

Additionally, a “primary” entry also receives the bare {UPPER(provider)}_{suffix} key for convenience. The primary entry is the one whose name matches the provider (e.g. an entry named anthropic using provider: anthropic); if no entry name matches, the first alphabetically is primary.

When the entry name equals the provider name, the redundant qualified form (e.g. ANTHROPIC_ANTHROPIC_API_KEY) is omitted and only the bare key is produced.

Examples (single entry):

• models.primary with provider: anthropic → ANTHROPIC_API_KEY
• integrations.github with provider: github → GITHUB_TOKEN
• knowledge.vectors with provider: pinecone → PINECONE_API_KEY

Examples (duplicate entries, two anthropic models):

• models.anthropic + models.sonnet both with provider: anthropic:
  • anthropic (name matches provider, primary) → ANTHROPIC_API_KEY
  • sonnet → ANTHROPIC_SONNET_API_KEY

Cloud provider credentials are always required.

8.2 Self-Hosted Provider Connection Details

Self-hosted providers deploy a container. The platform injects connection env vars using the provider’s env prefix:

Single entry for a provider:

{EnvPrefix}_HOST, {EnvPrefix}_PORT, {EnvPrefix}_URL

Example: one qdrant knowledge entry → QDRANT_HOST, QDRANT_PORT, QDRANT_URL.

Multiple entries for the same self-hosted provider:

Each entry gets name-qualified keys; the first alphabetically also gets bare keys:

{EnvPrefix}_{UPPER(entry_name)}_HOST  (plus bare {EnvPrefix}_HOST for first)

Model providers additionally inject {EnvPrefix}_BASE_URL (with /api appended) and {EnvPrefix}_MODEL as a comma-separated list of model identifiers when models (or the deprecated model) is specified.

8.3 Container-Mode Connection Details

Container-mode entries (no provider) receive generic section-prefixed env vars:

• Models: MODEL_{UPPER(name)}_HOST, MODEL_{UPPER(name)}_PORT, MODEL_{UPPER(name)}_URL
• Knowledge: KNOWLEDGE_{UPPER(name)}_HOST, KNOWLEDGE_{UPPER(name)}_PORT
• Integrations: INTEGRATION_{UPPER(name)}_HOST, INTEGRATION_{UPPER(name)}_PORT, INTEGRATION_{UPPER(name)}_URL

8.4 Inputs

Inputs are user-supplied values prompted at deploy time. Each input’s name is used directly as the env var key (no prefix) in the target container:

providers[].variables is a template only; it declares what variables a provider requires so the platform can prompt for them at deploy time.

Example: inputs: [{name: OPENAI_API_KEY, datatype: secret}] → OPENAI_API_KEY in the target container.

8.5 Name Sanitization

Entry names used in env var keys are sanitized: converted to lowercase, hyphens, underscores and dots replaced with underscores, non-alphanumeric characters removed, consecutive underscores collapsed, then uppercased. For example, entry name my-model sanitizes to my_model, then uppercases to MY_MODEL.

9. Validation Rules

Implementations MUST enforce the following validation rules:

1. spec MUST be a non-empty string.
2. name MUST be a non-empty string.
3. agent MUST specify exactly one of image or build. If build is present, build.context and build.dockerfile are REQUIRED.
4. For each entry in models: provider and container are mutually exclusive. Exactly one MUST be present.
5. For each entry in knowledge: provider and container are mutually exclusive. Exactly one MUST be present.
6. For each entry in integrations: provider and container are mutually exclusive. Exactly one MUST be present.
7. For each entry in providers: scope MUST be present and contain one or more of models, knowledge, integrations. variables MUST be present and MUST contain at least one element. Each variable MUST have a non-empty name and a valid datatype.
8. When a component entry references a custom provider by name, the referencing section MUST be listed in that provider’s scope.
9. For each entry in ingestion: both container and trigger are REQUIRED. trigger.type MUST be one of schedule, startup, manual, webhook.
10. When a BuildConfig is provided (in agent.build, container.build), context and dockerfile are REQUIRED.
11. When gpu.runtime is provided, it MUST be one of cuda or rocm.
12. For each entry in models: models and model are mutually exclusive. Providing both is invalid. model is deprecated; implementations SHOULD emit a warning when it is used.
13. When an input’s display-as is select, options MUST be present and non-empty.
14. Each Input in any context MUST have a non-empty name and datatype MUST be one of string, boolean, number, array, object.
15. When agent.interfaces.frontend is true, the agent MUST serve HTTP on port 80.
16. When agent.interfaces.messaging is true, the agent MUST implement the messaging protocol.

Appendix A: Provider Registries (Non-Normative)

The following tables document the platform’s built-in provider registries as of this specification version. Implementations MAY extend these registries.

A.1 Model Providers

Self-Hosted

When models is specified for a self-hosted provider, the platform pulls all listed models and sets {ENV_PREFIX}_MODEL to the comma-separated list (e.g. OLLAMA_MODEL=llama3.2,mistral). The deprecated model field is treated as a single-element list.

Cloud

A.2 Knowledge Providers

Self-Hosted

Cloud

A.3 Integration Providers

Cloud

Appendix B: JSON Schema

A machine-readable JSON Schema for this specification is maintained at astropods.schema.json in the astro-spec package. The schema is generated from the normative type definitions and MAY be used for editor autocompletion and pre-validation.

Schema ID: https://astropods.com/schema/package.json

Appendix C: Complete Example

1
spec: blueprint/v1
2
name: engineering-assistant
3
4
agent:
5
  build:
6
    context: .
7
    dockerfile: Dockerfile
8
    secrets:
9
      - id: npm_token
10
        env: GITHUB_PACKAGES_TOKEN
11
  interfaces:
12
    frontend: true
13
    messaging: true
14
  inputs:
15
    - name: LOG_LEVEL
16
      datatype: string
17
      default: info
18
      description: Agent log level
19
20
inputs:
21
  ALLOWED_ORIGINS:
22
    name: ALLOWED_ORIGINS
23
    datatype: string
24
    description: Comma-separated list of allowed CORS origins
25
    optional: true
26
27
models:
28
  local_llm:
29
    provider: ollama
30
    models: [llama3.2, mistral]
31
32
  primary:
33
    provider: anthropic
34
35
  embedder:
36
    container:
37
      build:
38
        context: ./embedder
39
        dockerfile: Dockerfile
40
      port: 8000
41
      healthcheck:
42
        path: /health
43
    inputs:
44
      - name: EMBEDDING_BATCH_SIZE
45
        datatype: number
46
        default: "32"
47
        description: Number of texts to embed per request
48
49
knowledge:
50
  docs:
51
    provider: qdrant
52
    persistent: true
53
54
  cache:
55
    provider: redis
56
57
  db:
58
    container:
59
      image: pgvector/pgvector:pg17
60
      port: 5432
61
      volume: /var/lib/postgresql/data
62
    persistent: true
63
    inputs:
64
      - name: POSTGRES_DB
65
        datatype: string
66
        default: my_db
67
        description: Database name
68
      - name: POSTGRES_USER
69
        datatype: string
70
        default: postgres
71
      - name: POSTGRES_PASSWORD
72
        datatype: string
73
        secret: true
74
        description: Postgres superuser password
75
76
integrations:
77
  github:
78
    provider: github
79
80
  jira:
81
    provider: my-jira    # references custom provider below
82
83
providers:
84
  my-jira:
85
    scope: [integrations]
86
    variables:
87
      - name: API_KEY           # → MY_JIRA_API_KEY
88
        datatype: string
89
        secret: true
90
        description: Jira API key
91
      - name: BASE_URL          # → MY_JIRA_BASE_URL
92
        datatype: string
93
        display-as: short-text
94
        description: Jira instance URL
95
      - name: PROJECT           # → MY_JIRA_PROJECT
96
        datatype: string
97
        display-as: select
98
        options: [ENG, PLATFORM, INFRA]
99
        description: Default Jira project
100
      - name: HMAC_SECRET       # → MY_JIRA_HMAC_SECRET
101
        datatype: string
102
        secret: true
103
        description: Shared secret for HMAC signing
104
        optional: true
105
106
ingestion:
107
  docs_sync:
108
    container:
109
      image: my-docs-sync:latest
110
      environment:
111
        SOURCE_REPO: company/engineering-docs
112
        TARGET_COLLECTION: docs
113
    trigger:
114
      type: schedule
115
    inputs:
116
      - name: SYNC_BATCH_SIZE
117
        datatype: number
118
        default: "100"
119
        description: Number of documents to sync per batch
120
121
  initial_load:
122
    container:
123
      image: my-bootstrap-worker:latest
124
    trigger:
125
      type: startup
126
127
dev:
128
  interfaces:
129
    frontend:
130
      port: 3000
131
    messaging:
132
      adapters: [slack]
133
      slack:
134
        actionable_reactions: [ticket]
135
  command: bun --watch run start