Deployment manifest

The deployment manifest is named squid.yaml by convention. It defines the Cloud deployment identity, build, services, addons, environment, and resource profiles used by sqd deploy.

Use manifest_version, slot or tag, and deploy.init in new manifests. The older manifestVersion, numeric version, and deploy.migrate fields are accepted for backwards compatibility but are deprecated.

Minimal manifest

squid.yaml

manifest_version: subsquid.io/v0.1
name: sample-squid

build:

deploy:
  addons:
    postgres:
  processor:
    cmd: ["sqd", "process:prod"]
  api:
    cmd: ["sqd", "serve:prod"]

With no slot or tag, sqd deploy . creates a new slot with a generated identifier. See Slots and tags before choosing a production deployment strategy.

Field	Description	Required
`manifest_version`	Manifest schema. The supported value is `subsquid.io/v0.1`.	Yes
`name`	Squid name. Use 3 to 30 lowercase letters, numbers, or dashes. It cannot start or end with a dash.	Yes, unless supplied through the CLI
`slot`	Deploy to or update this slot. Use 2 to 6 lowercase letters, numbers, or dashes.	No
`tag`	Deploy to the slot currently carrying this tag. Use 2 to 32 lowercase letters, numbers, or dashes.	No
`description`	Reader-facing description shown in Cloud.	No

slot and tag are mutually exclusive. If neither is present, Cloud creates a new slot.

A tag identifies the slot that currently carries it. Deploying through a production tag updates that slot in place. If the change requires a fresh database or historical replay, create a new slot and move the tag only after validation.

`build`

Cloud builds one image and runs it with different commands for init, processor, and api.

Field	Values	Default	Purpose
`dockerfile`	Path	`Dockerfile`	Use a custom Dockerfile from the squid source
`node_version`	`18`, `20`, `21`	`20`	Node.js version used by the managed build
`package_manager`	`auto`, `npm`, `pnpm`, `yarn`	`auto`	Package manager used for dependency installation
`install.cmd`	String array	Detected package-manager install command	Override dependency installation
`cmd`	String array	Project default	Override the build command

The following files must exist in the squid source:

package.json
tsconfig.json
commands.json
src/

The db/ and assets/ directories are included when present. Example:

build:
  node_version: "20"
  package_manager: pnpm
  install:
    cmd: ["pnpm", "install", "--frozen-lockfile"]
  cmd: ["pnpm", "build"]

`deploy`

The deploy section is required and contains the services and addons that make up the squid.

`addons`

`postgres`

Provision managed Postgres:

deploy:
  addons:
    postgres:
      version: "18"
      config:
        statement_timeout: 60s
        log_min_duration_statement: 5s
        idle_in_transaction_session_timeout: 60s
        idle_session_timeout: 10min
        max_locks_per_transaction: 64
        max_pred_locks_per_transaction: 64
      external_access:
        max_connections: 10

Supported Postgres versions are 14, 15, 16, 17, and 18. Cloud injects the connection variables described in the Postgres reference. Duration fields accept an integer number of milliseconds or a value ending in us, ms, s, min, h, or d.

`rpc`

Provision one or more Cloud RPC endpoints:

deploy:
  addons:
    rpc:
      - eth.http
      - arbitrum-one.http

See RPC proxy networks for valid names and RPC proxy for usage.

`hasura`

Provision Hasura instead of an application-managed GraphQL server:

deploy:
  addons:
    hasura:
      version: latest
      env:
        HASURA_GRAPHQL_ENABLE_CONSOLE: "false"

See Hasura for initialization and API configuration.

`init`

init runs to completion before processor and API services start. Use it for database migrations or one-time deployment initialization:

deploy:
  init:
    cmd: ["sqd", "migration:apply"]
    env:
      SQD_DEBUG: "sqd:migration"

When Postgres is enabled and init is omitted, Cloud uses:

init:
  cmd: ["npx", "squid-typeorm-migration", "apply"]

If init exits with an error, the deployment does not start.

`processor`

A single processor:

deploy:
  processor:
    cmd: ["sqd", "process:prod"]
    env:
      SQD_INFO: "sqd:processor"

Multiple processors:

deploy:
  processor:
    - name: ethereum
      cmd: ["node", "lib/main.js", "ethereum"]
    - name: base
      cmd: ["node", "lib/main.js", "base"]

Names are required and must be unique when processor is a list. Each entry runs as a separate service and is billed separately. Processor services can run any executable included in the built image. That includes non-indexing workloads such as background and scheduled jobs.

`api`

api is optional. Add it when the deployment serves GraphQL or another HTTP API:

deploy:
  api:
    cmd: ["sqd", "serve:prod"]
    env:
      SQD_INFO: "sqd:graphql-server"

The server must listen on the Cloud-provided GRAPHQL_SERVER_PORT. Cloud exposes APIs through slot and tag URLs:

https://<org>.squids.live/<name>@<slot>/api/graphql
https://<org>.squids.live/<name>:<tag>/api/graphql

Use a tag URL in production so the destination can move between slots without changing clients.

`env`

Deployment-level variables are available to every service:

deploy:
  env:
    NETWORK: ethereum-mainnet
  processor:
    cmd: ["sqd", "process:prod"]
    env:
      SQD_DEBUG: "sqd:processor"

Service-level variables override deployment-level variables. See Environment variables and secrets.

`cors`

Configure the Cloud API proxy:

deploy:
  cors:
    enabled: true
    allow_origin:
      - https://app.example.com
    allow_methods:
      - GET
      - POST
    allow_headers:
      - Content-Type
      - Authorization
    allow_credentials: true
    max_age: 3600

Available fields are enabled, allow_origin, allow_methods, allow_headers, expose_headers, allow_credentials, and max_age.

`scale`

The scale section selects dedicated or collocated placement and resource profiles:

scale:
  dedicated: true
  addons:
    postgres:
      profile: medium
      storage: 100Gi
      autoresize: true
      autoresize_limit: 250Gi
  processor:
    profile: medium
  api:
    profile: large
    replicas: 3

version belongs under deploy.addons.postgres, not scale.addons.postgres. Scaling changes resources; it does not change the database engine version.

See Scaling and Postgres for allowed profiles, replicas, storage, and billing behavior.

Secrets

Reference an organization secret with the secrets context:

deploy:
  env:
    RPC_ENDPOINT: "${{ secrets.FAST_RPC_ENDPOINT_URL }}"

Secrets are organization-scoped. Changing a secret does not update running processes until the deployment is restarted:

sqd restart -n <name> -s <slot>

Never store credentials directly in squid.yaml.

Production example

squid.yaml

manifest_version: subsquid.io/v0.1
name: account-history

build:
  node_version: "20"
  package_manager: pnpm

deploy:
  addons:
    postgres:
      version: "18"
      config:
        statement_timeout: 60s
        log_min_duration_statement: 5s
        idle_in_transaction_session_timeout: 60s
    rpc:
      - eth.http
  env:
    NETWORK: ethereum-mainnet
  init:
    cmd: ["sqd", "migration:apply"]
  processor:
    cmd: ["sqd", "process:prod"]
  api:
    cmd: ["sqd", "serve:prod"]

scale:
  dedicated: true
  addons:
    postgres:
      profile: medium
      storage: 100Gi
      autoresize: true
      autoresize_limit: 250Gi
  processor:
    profile: medium
  api:
    profile: medium
    replicas: 2

Deploy it into a new generated slot:

sqd deploy .

After validation, attach a stable tag:

sqd tags add production -n account-history -s <slot>

Managed

Self-Hosting

Minimal manifest

Header

`build`

`deploy`

`addons`

`postgres`

`rpc`

`hasura`

`init`

`processor`

`api`

`env`

`cors`

`scale`

Secrets

Production example

​Minimal manifest

​Header

​build

​deploy

​addons

​postgres

​rpc

​hasura

​init

​processor

​api

​env

​cors

​scale

​Secrets

​Production example

Minimal manifest

Header

`build`

`deploy`

`addons`

`postgres`

`rpc`

`hasura`

`init`

`processor`

`api`

`env`

`cors`

`scale`

Secrets

Production example