bahama.yaml reference

bahama.yaml is the short, committed description of the infrastructure an application should have. You and your coding agents can read and edit it. Bahama validates it and plans the provider work needed to make live resources match.

The manifest contains intent. Provider account IDs, resource IDs, connection strings, tokens, and other discovered state do not belong in it.

Minimal structure

version: 1
 
project:
  name: my-app
 
application:
  framework: vite-spa
 
environments:
  production:
    provider: bahama-cloud

Top-level keys are strict. A misspelling fails validation instead of being silently ignored.

version

The current manifest version is 1:

version: 1

project

project:
  name: community-notes

name is the portable stack name and the default provider-facing project name. It must be 1–64 characters using lowercase letters, numbers, and hyphens, and it must begin with a letter or number.

Some providers accept a safe config.name override when their resource should use a different display name.

application

application:
  framework: nextjs
  dir: apps/web

• framework is required when the manifest defines environments. Every hosted environment must support it.
• dir is optional and points to the deployable application inside the repository. The path must stay within the project.

Use bahama inspect --json and the live provider catalog before choosing a framework identifier.

environments

Environments are places where the application runs or receives configuration:

environments:
  local:
    provider: local
  production:
    provider: vercel

Each key is the environment name. Names use lowercase letters, numbers, and hyphens. local and production are conventions, not reserved behavior; the selected provider defines what the environment can do.

An environment accepts:

• provider — the provider ID; and
• config — optional non-secret configuration validated by that provider.

For example, a selected Vercel team may be written after a Bahama decision:

environments:
  production:
    provider: vercel
    config:
      scope: example-team

resources

Resources are services the application depends on:

resources:
  database:
    provider: neon
    engine: postgres

The resource key—database here—is the project’s readable name for it. A resource accepts:

• provider — the provider ID;
• engine — an optional provider-supported engine;
• environment — the environment that owns a provider-native resource; and
• config — optional non-secret provider configuration.

A provider-native resource must name an environment on the same provider:

resources:
  database:
    provider: bahama-cloud
    environment: production

bindings

Bindings connect a capability produced by one provider to environments that consume it:

bindings:
  DATABASE_URL:
    from: resources.database.connectionUrl
    to:
      - environments.local.variables
      - environments.production.variables

The binding key becomes the destination variable name. It must begin with an uppercase letter and contain only uppercase letters, numbers, and underscores.

Addresses use these forms:

resources.<resource-name>.<capability>
environments.<environment-name>.<capability>

to may be one address or a non-empty list. The source must produce the named capability and each destination must consume it. bahama plan validates the composition before anything changes.

When a produced capability is secret, Bahama moves it as an opaque reference. The value is never serialized into the manifest, plan, lock, or receipt.

Complete Vercel and Neon example

version: 1
 
project:
  name: community-notes
 
application:
  framework: nextjs
 
environments:
  local:
    provider: local
  production:
    provider: vercel
 
resources:
  database:
    provider: neon
    engine: postgres
 
bindings:
  DATABASE_URL:
    from: resources.database.connectionUrl
    to:
      - environments.local.variables
      - environments.production.variables

Values that never belong here

Do not add:

• provider account, organization, team, project, database, or deployment IDs;
• connection strings, passwords, tokens, API keys, or secret literals;
• values copied from bahama.lock; or
• capabilities not declared by the live provider guide.

The validator rejects common ID-shaped keys even inside provider config. When planning returns a decision, write only the selected value to the exact writeBack path it provides.

Current manifest limits

• Environments require an application framework.
• A project can currently use a provider for only one environment.
• A native resource and its owning environment must use the same provider.
• The manifest cannot request destruction, selectively detach a resource, or contain arbitrary raw secrets.
• New manifests use environments; the CLI may parse an older application- provider shape only for compatibility.