Overview

slipway.yaml describes the services your project runs and the databases they need.

Where the spec comes from

slipway resolves one spec per repository, in this order:

Source	What it is
A committed `slipway.yaml`	The native manifest. Full control over services, ports, disks, health checks and secrets.
A committed `docker-compose.yml`	Your existing Compose file, read and converted on every deploy. See Docker Compose.
A stored spec	No file in the repository. slipway keeps the spec and you edit it in the console, which is how a repo slipway can only read still deploys.

A committed slipway.yaml wins unless you pin a Compose file, and a stored spec applies only when no committed file resolves at the spec path. Your repository stays the source of truth. slipway never writes a spec back to it and reads the file fresh on every push. The only thing you manage in the console is the secret and variable values your spec references.

For a monorepo, set a per-service spec path such as services/api/slipway.yaml and slipway resolves the spec from there. See Monorepos.

A minimal spec

slipway.yaml

version: 1

services:
  - name: web
    runtime: docker
    ports:
      - port: 3000
        public: true
    healthCheckPath: /healthz

One service, built from the Dockerfile at the repository root, served on port 3000 at its own hostname, live once /healthz returns 2xx.

A fuller one

slipway.yaml

version: 1

autoDeploy: true

previews:
  generation: automatic

databases:
  - name: db
    engine: postgres
    version: "18"
    diskSizeGB: 10

services:
  - name: api
    rootDir: apps/api
    dockerTarget: production
    ports:
      - port: 8080
        public: true
    healthCheckPath: /healthz
    preDeploy: ["npm", "run", "migrate"]
    env:
      DATABASE_URL: ${service.db.url}
      STRIPE_KEY: ${secret.STRIPE_KEY}
    cpu: 1
    memory: 1GB

  - name: worker
    type: worker
    rootDir: apps/worker
    runtime: node
    runtimeVersion: "22"
    buildCommand: npm ci && npm run build
    command: ["node", "dist/queue.js"]
    env:
      DATABASE_URL: ${service.db.url}

  - name: site
    type: static
    rootDir: apps/site
    runtime: node
    buildCommand: npm run build
    publish: dist
    notFound: /index.html

Top-level fields

Field	Type	Required	Notes
`version`	int	Required.	Currently `1`.
`services`	list	Required.	One block per service, each starting with `- name:`. At least one.
`databases`	list	Optional.	Managed databases. Each entry becomes a service. See Databases.
`autoDeploy`	bool	Optional.	Whether a push to the tracked branch redeploys.
`buildFilter`	object	Optional.	`paths` and `ignoredPaths` globs. See Monorepos.
`previews`	object	Optional.	`generation:` is `automatic`, `manual` or `off`.

Everything else lives inside a service block. See Services.

autoDeploy

slipway.yaml

version: 1
autoDeploy: true

services:
  - name: web
    runtime: docker
    ports:
      - port: 3000
        public: true

The committed file wins over the console toggle whenever it says something, and the change is recorded on the deploy that carried it, so a setting that appears to have reverted has a visible cause in the event log. Omit the field and the console toggle keeps whatever you set there.

previews

slipway.yaml

version: 1

previews:
  generation: automatic     # automatic | manual | off

services:
  - name: web
    runtime: docker
    ports:
      - port: 3000
        public: true

automatic spawns a preview for every qualifying PR, manual waits for the slipway-preview label or a [slipway preview] title tag, and off is the default. Like autoDeploy, the file wins over the console setting whenever it says something. Previews are a plan capability, so on a plan without them the setting is skipped rather than failing your push. See PR previews.

Validation

slipway checks your spec in two places. At parse time, on every push and whenever you add a repo to a project. This catches missing required fields, invalid service names, a service with both image and build fields or neither, two services claiming the same public hostname, and unknown keys. A typo such as enviroment: fails immediately with its line number, and nothing is built. At deploy time, once a deploy starts. Unverified custom domains, bad ${service.*} references, a managed database whose password secret is missing, and build, image-pull or health-check failures mark the deployment failed with the reason in the event log. Other missing ${secret.*} / ${var.*} references warn in the deploy log and leave the referencing key unset instead of failing — see Secrets and variables. See Troubleshooting for the errors you are most likely to hit.

Moving from the older shape

Earlier specs keyed services by name and nested build fields under build:. That shape no longer parses.

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      target: production
    ports:
      - { port: 8080, public: true, domain: acme.com }
    depends_on: [db]
    workdir: /app

services:
  - name: api
    rootDir: ./api
    dockerfilePath: Dockerfile
    dockerTarget: production
    ports:
      - port: 8080
        public: true
    domain: acme.com
    dependsOn: [db]
    workDir: /app

Top-level volumes: and predeploy: are gone as well. A service gets its own disk, and the migrations hook is preDeploy on the service that owns it. The parser names the replacement for each retired spelling, so a stale file reports what to write instead.

What slipway leaves out

Not supported	Do this instead
Init containers and sidecars	Run pre-start work from your start command, or define a separate service.
`extends:` and spec composition	Not available. Tell us if you need it.
Volumes shared between services	Give each service its own disk, or put the shared data in a database or a bucket.

Stability

The spec is version: 1. New fields are additive and optional, so a working slipway.yaml keeps working. A breaking change would land as version: 2.

Services

Every field of a service block.

Databases

Postgres, Redis, MySQL and ClickHouse in four lines.

Secrets and variables

Substitution syntax and where the values live.

Field index

Every field, one row each.

Get started

Quickstarts

Services

Data

Deploys

Previews

slipway.yaml

Networking

Projects

Observability

Integrations

Organization

Clusters

Reference

Where the spec comes from

A minimal spec

A fuller one

Top-level fields

autoDeploy

previews

Validation

Moving from the older shape

What slipway leaves out

Stability

Services

Databases

Secrets and variables

Field index

​Where the spec comes from

​A minimal spec

​A fuller one

​Top-level fields

​autoDeploy

​previews

​Validation

​Moving from the older shape

​What slipway leaves out

​Stability

Services

Databases

Secrets and variables

Field index

Where the spec comes from

A minimal spec

A fuller one

Top-level fields

autoDeploy

previews

Validation

Moving from the older shape

What slipway leaves out

Stability