Interfaces

apprail.yml

A small file in your repository that describes the project and its services. Your editor validates it, apprail plan compares it with what’s running, and coding agents read it to understand your app.

Create one

Terminal

apprail init --name Shop --slug shop --git https://github.com/acme/shop
apprail inspect           # validate and show it with defaults filled in
apprail plan              # what would change in your workspace

init never overwrites an existing file. The file starts with a schema comment, so editors with YAML language support autocomplete and validate it as you type.

Example

# yaml-language-server: $schema=https://console.apprail.io/api/apprail.schema.json
version: apprail.io/v1alpha1
project:
  name: Shop
  slug: shop
services:
  - name: web
    type: web
    environment: production
    source:
      type: git
      repository: https://github.com/acme/shop
      ref: main
      context: services/web
      dockerfile: Dockerfile
    runtime:
      port: 3000
      healthCheck: /healthz
      instances: 2
      cpu: 500        # millicores
      memory: 1024    # MB
  - name: worker
    type: worker
    source:
      type: image
      image: ghcr.io/acme/shop-worker:1.4
    runtime:
      cpu: 250
      memory: 512

Reference

Field	Default	Rules
`version`	—	Must be `apprail.io/v1alpha1`
`project.name`	—	1–80 characters
`project.slug`	—	Lowercase letters, digits, and single hyphens; up to 63 characters
`services[].name`	—	Unique; lowercase letters, digits, and single hyphens; up to 40 characters
`services[].type`	`web`	`web` or `worker`
`services[].environment`	`production`	`production` or `staging`
`services[].region`	`lt-sil-1`	The only region today
`source.type`	—	`git` or `image`. Leave `source` out while designing; `plan` then asks you to add one
`source.repository`	—	An HTTPS Git URL without credentials
`source.ref`	`main`	Branch, tag, or commit
`source.context`	`.`	Build directory, relative to the repository root
`source.dockerfile`	`Dockerfile`	Relative to the build context. If it doesn’t exist, the framework is detected
`source.image`	—	Any image reference, for image sources
`runtime.port`	—	1–65535 for web services; leave it out for workers
`runtime.healthCheck`	`/`	Starts with `/`, up to 200 characters
`runtime.instances`	1	1–20
`runtime.cpu`	250	50–8000 millicores
`runtime.memory`	512	64–32768 MB

Unknown fields are rejected, so a typo is an error that names the field rather than a setting that silently does nothing.

Planning

apprail plan signs in read-only, compares the file with your workspace, and lists what it would create or change. It never changes anything. Differences the API can’t apply from a manifest yet are marked as blocked rather than glossed over. With --json the output is a stable, versioned format (apprail.plan/v1) that CI and agents can rely on.

Today the manifest describes and plans; you still create and deploy with the CLI, console, or API. An apprail apply that carries out a plan — with confirmation and the same permissions — is planned.

The JSON Schema is published at https://console.apprail.io/api/apprail.schema.json and advertised by GET /api/v1/capabilities.