convox.yml

convox.yml is a manifest used to describe your application and all of its infrastructure needs.

environment:
  - COMPANY=Convox
  - DOCS_URL
labels:
  team: platform
configs:
  - id: app-config
appSettings:
  awsLogs:
    cwRetention: 31
    disableRetention: false
resources:
  database:
    type: postgres
    options:
      storage: 200
  queue:
    type: redis
services:
  api:
    annotations:
      - test.annotation.org/value=foobar
    build: .
    command: bin/api
    environment:
      - ENCRYPTION_KEY
    health: /check
    internal: true
    port: 3000
    resources:
      - database
      - queue
    termination:
      grace: 45
    test: make test
    timeout: 120
    deployment:
      minimum: 50
      maximum: 200
  web:
    build: .
    command: bin/web
    environment:
      - SESSION_SECRET
    port: 3000
  worker:
    build: ./worker
    command: bin/worker
    environment:
      - ENCRYPTION_KEY
    resources:
      - database
      - queue
  metrics:
    agent: true
    image: awesome/metrics
  inference:
    image: nvcr.io/nim/meta/llama-3.1-8b-instruct:latest
    imagePullSecrets:
      - registry: nvcr.io
        username: $oauthtoken
        passwordEnv: NGC_API_KEY
timers:
  cleanup:
    schedule: "0 3 * * *"
    command: bin/cleanup
    service: worker

environment

The top-level environment section defines Environment Variables that are available to every Service.

environment:
  - COMPANY=Convox  # has a default value of "Convox"
  - DOCS_URL        # must be set before deployment

See Environment Variables for configuration options.

app settings

The appSettings section defines settings that apply exclusively to a particular app within the rack. These settings are independent of the global rack-level parameters and provide a mechanism for tailoring configuration to individual applications.

appSettings:
  awsLogs:
    cwRetention: 31
    disableRetention: false

See App Settings for configuration options.

resources

The resources section defines network-accessible Resources such as databases that can be made available to Services.

resources:
  database:
    type: postgres
    options:
      storage: 200

See Resource for configuration options.

services

The services section defines horizontally-scalable Services that can be optionally placed behind a load balancer.

services:
  api:
    build: .
    command: bin/api
    environment:
      - ENCRYPTION_KEY
    health: /check
    internal: true
    port: 3000
    resources:
      - database
      - queue
    test: make test

See Service for configuration options. A Service can also be declared as an Agent to run one process on every node.

labels

The top-level labels section defines labels applied to all Services in the app. Service-level labels override top-level labels with the same key.

labels:
  team: platform
  cost-center: engineering

The following label keys are reserved and cannot be used: system, rack, app, name, service, release, type.

configs

The configs section defines named configuration objects that can be mounted into service containers as files.

configs:
  - id: app-config

See Config Mounts for configuration options.

timers

The timers section defines Processes that run periodically on a set interval.

timers:
  cleanup:
    schedule: "0 3 * * *"
    command: bin/cleanup
    service: worker

See Timer for configuration options.

balancers

The balancers section defines custom TCP/UDP load balancers for Services that need to expose arbitrary ports.

balancers:
  custom:
    service: web
    ports:
      5000: 5001

See Balancer and Load Balancers for configuration options.

budget

The budget section declares the schema for monthly cost caps and the action taken when an app exceeds them. See Budget Caps for the operational guide and Cost Tracking for how spend is computed.

Persistence: enforcement-bearing fields (monthlyCapUsd, alertThresholdPercent, atCapAction, pricingAdjustment) are set at runtime via convox budget set or the Console budget tab — convox releases promote validates the manifest's budget: block but does not auto-write these fields. Auto-shutdown runtime fields (atCapWebhookUrl, notifyBeforeMinutes, shutdownGracePeriod, recoveryMode, shutdownOrder, neverAutoShutdown) are read fresh from the manifest each accumulator tick and take effect on the next deploy.

budget:
  monthlyCapUsd: 250
  alertThresholdPercent: 80
  atCapAction: auto-shutdown
  pricingAdjustment: 0
  notifyBeforeMinutes: 15
  shutdownGracePeriod: 30s
  recoveryMode: auto-on-reset
  shutdownOrder: largest-cost
  neverAutoShutdown:
    - api

Field	Description
monthlyCapUsd	Monthly cap in USD. Reset on the first of each month.
alertThresholdPercent	Percent of cap at which app:budget:threshold fires. Default 80.
atCapAction	One of alert-only, block-new-deploys, auto-shutdown.
atCapWebhookUrl	Optional webhook URL to notify when the cap fires.
pricingAdjustment	Multiplier applied to compute spend (e.g. 1.10 for a 10% markup).
notifyBeforeMinutes	(auto-shutdown only) Minutes between :armed and :fired.
shutdownGracePeriod	(auto-shutdown only) Pod terminationGracePeriod for shutdown.
recoveryMode	(auto-shutdown only) auto-on-reset or manual.
shutdownOrder	(auto-shutdown only) largest-cost or newest.
neverAutoShutdown	(auto-shutdown only) List of services that must remain up.

See Also

• App Definition for a hub of all app definition configuration topics
• Networking for network configuration including load balancers, DNS, and custom domains
• Environment Variables for configuring app settings
• Health Checks for configuring service health checks
• Scaling for controlling service scale and autoscaling
• Config Mounts for mounting configuration files into containers
• Deploying Changes for the --external build flag that bypasses source upload