> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# The scaling.yml file

> Every key in the file that tells Scaling how to boot your stack, with the rules each one is checked against.

`scaling.yml` sits at the root of your repository and says how your stack starts: what to install, which background services it needs, which processes to run, and how to tell that each one is up.

The file is checked before anything acts on it.
A problem is reported with the key as you wrote it, the line, and what is wrong, for example `processes.web.port` on line 12.

## A complete file

This is a monorepo with a web application and an API over one Postgres database.

```yaml theme={null}
version: 1
image: node:24
install: pnpm install --frozen-lockfile
services:
  postgres:
    init:
      - initdb -D /vercel/sandbox/.data/postgres
      - createdb app
    run: postgres -D /vercel/sandbox/.data/postgres
    health: { tcp: 5432 }
setup:
  - pnpm db:migrate
  - pnpm db:seed
processes:
  api:
    run: pnpm --filter api dev
    port: 3001
    health: /health
  web:
    run: pnpm --filter web dev
    port: 3000
    health: /
    env:
      API_URL: ${processes.api.url}
test: pnpm test:unit
env:
  DATABASE_URL: postgres://app@localhost:5432/app
login:
  process: web
  path: /sign-in
  user: owner@example.test
```

A single application needs much less.

```yaml theme={null}
version: 1
install: pnpm install --frozen-lockfile
processes:
  web: { run: pnpm dev, port: 3000, health: / }
test: pnpm test
```

## Rules that apply to the whole file

* A key the file does not have is an error, not something that is ignored. A misspelled key would otherwise look like it worked.
* YAML aliases (`&name` and `*name`) are not allowed. Write the value out.
* The file can be at most 64 KiB.
* Names of services and processes are lowercase letters, digits and dashes, starting with a letter, up to 32 characters.
* A command can be at most 2000 characters. Wherever a list of commands is accepted, it can hold at most 32.

## `version`

Required.
The only value is `1`.

## `image`

Optional.
The base image the stack boots from.
One of `node:22`, `node:24`, `node:26`, `python:3.14`, `ubuntu` or `universal`.
When it is left out, `node:24` is used.

## `install`

Required.
The command, or list of commands, that installs your dependencies.

```yaml theme={null}
install: pnpm install --frozen-lockfile
```

## `services`

Optional.
Background processes your stack needs before it can start, such as a database.
There can be at most 16.

Each service has:

| Key | Required | What it is |
| - | - | - |
| `run` | Yes | The command that starts the service. |
| `init` | No | A command, or list of commands, that prepares the service before it is started. |
| `env` | No | Environment for this service, on top of the shared `env`. |
| `health` | Yes | How to tell it is up: `{ tcp: <port> }` or `{ http: <path>, port: <port> }`. |

A service cannot have the same name as a process.

## `setup`

Optional.
A command, or list of commands, that runs once your services are up and before your processes start.
This is where migrations and seed data go.

Write these so they are safe to run more than once.

## `processes`

Optional.
The applications that make up your stack.
There can be at most 16.

Each process has:

| Key | Required | What it is |
| - | - | - |
| `run` | Yes | The command that starts the process. |
| `port` | Yes | The port it listens on, from 1024 to 65535. No two processes share a port. |
| `health` | Yes | A path, starting with `/`, that answers once the process is up. |
| `env` | No | Environment for this process, on top of the shared `env`. |

Your process must listen on `0.0.0.0`, not `127.0.0.1`.

## `test`

Optional.
The command that runs your tests.

## `env`

Optional.
Environment shared by every service and process.
A value set on a service or process wins over the same name here.

Names are letters, digits and underscores, and do not start with a digit.
Values are strings, numbers or `true` and `false`, at most 4096 characters.

<Warning>
  Do not put a real secret in this file. Everything written here is readable by every command that
  runs in your stack. Use placeholder values.
</Warning>

### Referring to another process

A value can name the address of one of your processes as `${processes.<name>.url}`.
Use it wherever one process needs to find another.

```yaml theme={null}
processes:
  api: { run: pnpm api, port: 3001, health: /health }
  web:
    run: pnpm dev
    port: 3000
    health: /
    env:
      API_URL: ${processes.api.url}/v1
```

The process you name must be in the file.
This is the only reference there is; any other `${...}` is an error.

## `login`

Optional.
How to sign in to your running application with a user from your seed data.

| Key | Required | What it is |
| - | - | - |
| `path` | Yes | The sign-in path, starting with `/`. |
| `user` | Yes | The seeded user to sign in as. |
| `process` | When there is more than one process | The process to sign in through. |

## `egress`

Optional.
The hosts your stack asks to reach on the internet while it runs.
There can be at most 64.

Each entry is a host name and nothing else: no scheme, no port, no path, no wildcard and no IP address.

```yaml theme={null}
egress:
  - api.stripe.com
```

Listing a host here is a request.
It does not by itself make the host reachable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.