configuration

runix.yaml

Complete reference for the Runix configuration file.

The runix.yaml file defines your entire deployment. It lives in the root of your project and tells Runix what services to create, which repos to pull, and how to configure each one.

Minimal Example#

runix.yaml

yaml

name: my-app
services:
  - name: api
    type: web-service
    repo: https://github.com/alice/api

That is all you need. Runix detects the runtime, generates a Dockerfile, builds the image, and deploys it with a public URL.

Full Reference#

Top-Level Fields#

Field	Type	Required	Description
`name`	string	Yes	Project name. Used for grouping and display.
`services`	array	Yes	List of service definitions (see below).

Service Fields#

Field	Type	Required	Description
`name`	string	Yes	Unique name for this service. Used in URLs and CLI commands.
`type`	string	Yes	Service type. See below for all options.
`repo`	string	No*	GitHub repository URL. Required for code-based services.
`branch`	string	No	Git branch to deploy. Defaults to `main`.
`env`	map	No	Key-value pairs injected as environment variables.
`instance`	string	No	Instance type: `starter`, `standard`, or `pro`. Defaults to `starter`.
`build_command`	string	No	Override the detected build command.
`start_command`	string	No	Override the detected start command.
`health_check_path`	string	No	HTTP path for health checks (web services only). Example: `/health`.
`cron_schedule`	string	No	Cron expression for cron-job services. Example: `0 * * * *`.

The `repo` field is required for web-service, static-site, background-worker, cron-job, and private-service types. Database types (postgresql, redis, kafka) do not need a repo.

Service Types#

Type Value	Description
`web-service`	HTTP service with public URL, health checks, and auto-TLS
`static-site`	Static files served over HTTP (HTML, CSS, JS)
`background-worker`	Long-running process without HTTP endpoint
`cron-job`	Scheduled task using cron syntax
`postgresql`	Managed PostgreSQL database
`redis`	Managed Redis cache
`kafka`	Managed Kafka message broker
`private-service`	Internal service not exposed to the public internet

Complete Example#

runix.yaml

yaml

name: my-saas-app
services:
  # Web API with a database
  - name: api
    type: web-service
    repo: https://github.com/alice/api-server
    branch: main
    instance: standard
    health_check_path: /health
    env:
      PORT: "3000"
      NODE_ENV: production
      DATABASE_URL: "${db.connection_string}"
      REDIS_URL: "${cache.connection_string}"

  # Frontend static site
  - name: frontend
    type: static-site
    repo: https://github.com/alice/frontend
    branch: main
    build_command: pnpm build
    start_command: pnpm start

  # Background job processor
  - name: worker
    type: background-worker
    repo: https://github.com/alice/worker
    env:
      DATABASE_URL: "${db.connection_string}"

  # Daily cleanup task
  - name: cleanup
    type: cron-job
    repo: https://github.com/alice/scripts
    cron_schedule: "0 3 * * *"
    env:
      DATABASE_URL: "${db.connection_string}"

  # PostgreSQL database
  - name: db
    type: postgresql

  # Redis cache
  - name: cache
    type: redis

  # Internal microservice
  - name: auth-service
    type: private-service
    repo: https://github.com/alice/auth
    env:
      JWT_SECRET: "my-secret-key"

Variable Interpolation#

Use `${service-name.connection_string}` syntax to reference connection strings from database services. Runix automatically resolves these when deploying.

yaml

env:
  DATABASE_URL: "${db.connection_string}"
  REDIS_URL: "${cache.connection_string}"

The service name in the interpolation must match the name field of a database service in the same runix.yaml file.

projects

Environment Variables