kyper.yml Reference

Full example

name: "my-cool-app"
version: "1.2.0"
category: productivity

docker:
  dockerfile: "./Dockerfile"

processes:
  web: "bundle exec puma -C config/puma.rb"
  worker: "bundle exec sidekiq -C config/sidekiq.yml"

deps:
  - postgres: "15"
    storage_gb: 50
  - redis

storage:
  mounts:
    - path: storage
      storage_gb: 5
    - path: uploads

env:
  - OPENAI_API_KEY

capabilities:
  - email
  - payments

hooks:
  release: "bundle exec rails db:prepare"
  on_deploy: "bundle exec rails cache:warmup"
  on_update: "bundle exec rails cache:warmup"

healthcheck:
  path: "/up"
  initial_delay: 15
  interval: 30
  timeout: 10

pricing:
  one_time: 49.00
  subscription: 12.00

resources:
  min_memory_mb: 512
  min_cpu: 0.5

name required

The unique identifier for your app on Kyper. Used to construct your app's URL (kyper.shop/apps/my-cool-app). Cannot be changed after first push without creating a new app.

name: "invoice-hero"

version required

The current version of your app, following semantic versioning (MAJOR.MINOR.PATCH). Bump this on every push — Kyper enforces that each pushed version is greater than the previous.

version: "1.0.0"

category required

Used for marketplace filtering. Choose the most relevant category.

docker required

Configuration for the Docker build. Kyper builds your image from source — you do not need a container registry account.

processes required

A map of process type names to the commands that run them. At least one web process is required. The web process must bind to $PORT.

Each process runs independently using the same Docker image with a different command. Only the web process receives external traffic — all other processes run in the background without exposed ports.

processes:
  web: "bundle exec puma -C config/puma.rb"
  worker: "bundle exec sidekiq -C config/sidekiq.yml"
  scheduler: "bundle exec clockwork config/clock.rb"

Max 5 processes. Names: [a-z0-9-], max 63 chars. All share the same image, env vars, and deps. Adding/removing processes between versions is handled automatically.

deps

Backing services that Kyper provisions alongside your app. Each dep gets a managed instance with connection details injected as environment variables.

Formats

# Plain string (platform default version)
deps:
  - postgres
  - redis

# Version-pinned hash
deps:
  - postgres: "15"
  - redis: "6"

# With custom storage
deps:
  - postgres: "15"
    storage_gb: 50    # default: 20 GB
  - redis

App-local persistent storage

Use storage.mounts for framework-local files such as Rails Active Storage local, Django media uploads, Laravel storage/app, or explicit upload directories. Relative paths resolve against the image working directory. Up to 5 mounts are allowed; storage_gb is optional and must be 1-10 GB.

storage:
  mounts:
    - path: storage
      storage_gb: 5
    - path: /app/uploads

Supported versions

Storage is billed at $0.10/GB/month and included in the consumer-facing subscription price. Dep containers include readiness healthchecks — your app won't start until all deps are accepting connections.

S3-compatible object storage (s3)

Provisions a fully S3-compatible object storage service. Any AWS SDK (ActiveStorage, Shrine, boto3, etc.) works against it unmodified. The app bucket is auto-created on first write. Data persists across app updates. Version pinning not supported.

pricing at least one required

At least one pricing option must be set. Prices must be ≥ $1.00. Kyper takes a 15% commission; your net payout is 85% minus Stripe processing fees.

env

Declares the environment variable keys that consumers must supply before their deployment can start. Use this for API keys, third-party tokens, and other secrets that Kyper cannot inject automatically.

env:
  - OPENAI_API_KEY
  - STRIPE_SECRET_KEY
  - SENDGRID_API_KEY

Keys listed here are names only (no values). Consumers enter the values through the deployment configure page. Values are stored encrypted and injected at provision time.

Auto-injected variables

These are always available — do not list them in env:.

capabilities

Declares user-facing services your app needs. Kyper manages email, Google Maps, and Mapbox by default, while payments and SMS require the buyer to connect or provide their own service account before deploy.

capabilities:
  - email
  - maps
  - mapbox
  - payments
  - sms

Available capabilities

Legacy integrations: is no longer supported; use capabilities:. Do not list capability-provided keys in env: — they are injected automatically.

Managed email injects both RESEND_API_KEY and a verified sender address KYPER_MAIL_FROM. Read your "from" address from KYPER_MAIL_FROM; do not declare a sender in env:. See Services.

hooks

Commands that Kyper runs at key lifecycle points. release runs as a one-shot Job before your app pods start (after deps are ready). on_deploy and on_update run inside a healthy web pod, after pods are ready.

# Rails
hooks:
  release: "bundle exec rails db:prepare"
  on_deploy: "bundle exec rails cache:warmup"

# Prisma / Node
hooks:
  release: "prisma migrate deploy"

healthcheck

Controls how Kyper polls your app's health endpoint. Checked during provisioning, during updates, and on an ongoing schedule (3 consecutive failures mark the deployment as failed).

resources

Hints that Kyper uses to select the right server size for hosted subscriptions. These are minimums — Kyper may provision a larger size if needed. Consumers can also resize after deployment.

CPU hints can be fractional. These are hints — consumers pick their tier at subscribe time. See Pricing.

Validation rules

Kyper validates kyper.yml at push time. Run kyper check locally to catch issues before pushing. Common rejection reasons: