schema stackbone.ai/v1 · strict
agent.yaml
# Stackbone agent manifest. Schema: stackbone.ai/v1.# Reference: https://docs.stackbone.ai/docs/cli/reference/agent-yaml/
apiVersion: stackbone.ai/v1name: starter-ragruntime:  engine: node  entry: src/index.tsdatabase:  schema: ./src/schema.ts  migrations: ./.stackbone/migrationsdev:  autoMigrate: falserag:  embeddingModel: openai/text-embedding-3-small  autoMigrate: true
15 lines

Declare what your agent needs. We provision it per install.

You declare two blocks — a database and a retrieval index. Every agent also gets a full data plane: storage, a model key, queues and tracing. At install the control plane materializes all of it and injects the credentials. The creator never hardcodes a secret.

Read the agent.yaml docs Managed runtime
01 · What you declare — and the full stack every agent gets
2 declared · 2 always provisioned

Two blocks are real keys in the strict agent.yaml schema — declaring them gates the resource they bind to. The rest of the data plane is provisioned for every agent whether you name it or not.

Declared in agent.yaml— a key gates the resource
  • database:
    Dedicated Postgres

    relational + pgvector + tsvector + KV + _queue_jobs

    • DATABASE_URL
  • rag:
    pgvector index on the same Postgres

    embeddingModel from the manifest

    no separate credential — rides DATABASE_URL

Always provisioned— standard data plane, no key to declare
  • Object storageprovisioned by default
    Object storage bucket scoped to the agent

    S3-compatible blob storage

    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • S3_ENDPOINT
  • Model accessprovisioned by default
    OpenRouter sub-key · monthly limit

    openai SDK with a base-URL override

    • OPENROUTER_API_KEY
    • OPENROUTER_BASE_URL
LlamaParseopt-in — not yet a key in the shipped v1 schema

advanced document parsing, pay-per-page

  • LLAMA_PARSE_API_KEY
02 · Injected, never pasted

The saga writes the credentials straight into the agent's environment. Here is what printenv shows — every value masked.

$ printenv· read-only · values masked
# identity
PLATFORM_API_URL=••••
PLATFORM_API_KEY=••••
AGENT_ID=••••
AGENT_CONFIG={…}
WORKSPACE_ID=••••being renamed to ORGANIZATION_ID — migration tracked in the language-rename ADR
# persistence
DATABASE_URL=••••
# storage
AWS_ACCESS_KEY_ID=••••
AWS_SECRET_ACCESS_KEY=••••
S3_ENDPOINT=••••
# llm
OPENROUTER_API_KEY=••••
OPENROUTER_BASE_URL=••••
0 keys pasted— every credential above is injected by the saga and masked. The creator types none of them.
03 · Declared at publish
  • events / triggers
  • pricing
  • metadata

The shipped stackbone.ai/v1 manifest is reduced and strict; these are declared elsewhere today and land in the manifest as it grows (triggers, secrets, egress). Shown here as pending — never as live YAML.

Declare it once. We provision every install.

Read the agent.yaml docs Managed runtime