schema stackbone.ai/v1 · strict

agent.yaml

# Stackbone agent manifest. Schema: stackbone.ai/v1.# Run `stackbone docs agent-yaml` for the full reference.
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 · 4 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 Neon Postgres
relational + pgvector + tsvector + KV + _queue_jobs
DATABASE_URL
rag:
pgvector index on the same Neon
embeddingModel from the manifest
no separate credential — rides DATABASE_URL

Always provisioned— standard data plane, no key to declare

Object storageprovisioned by default
R2 bucket scoped to the agent
S3-compatible blob storage, no egress fees
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
Cross-container pushprovisioned by default
QStash publisher + HMAC key rotation
pay-per-message, HTTP-native
QSTASH_TOKEN
QSTASH_CURRENT_SIGNING_KEY
QSTASH_NEXT_SIGNING_KEY
Observabilityprovisioned by default
OpenTelemetry export
OTLP traces, metrics and logs
OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_RESOURCE_ATTRIBUTES

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=••••

# push

QSTASH_TOKEN=••••

QSTASH_CURRENT_SIGNING_KEY=••••

QSTASH_NEXT_SIGNING_KEY=••••

# observability

OTEL_EXPORTER_OTLP_ENDPOINT=••••

OTEL_RESOURCE_ATTRIBUTES=••••

0 keys pasted— every credential above is injected by the saga and masked (the QStash signing keys rotate). 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