Skip to main content

State

When sail deploy provisions a resource, it gets back an identifier (an ARN, a Kubernetes resource UID, a URL) and a bag of attributes. That information has to be persisted somewhere so the next deploy can adopt-and-update rather than re-create. That persisted blob is the state.

Where state lives​

State is per (project, target). On disk, in your project root:

.sail/
  state.aws.us-east-1.json
  state.sprintsail-runtime.my-cluster.json
  cutover-2026-05-30T00-44-34.sh        # generated by sail migrate

This is the local file backend — the default. It's the same pattern Terraform uses and works fine for solo projects and CI runs where the state can be checked in (or restored from artifact storage) between runs.

For multi-developer or production scenarios you'll want a remote state backend. The schema is reserved in v1; the implementation lands in v1.1:

// sail.config.ts
export default defineConfig({
  project: 'orders',
  defaultTarget: 'aws:us-east-1',
  state: {
    kind: 's3',
    bucket: 'mycompany-sail-state',
    dynamoTable: 'mycompany-sail-locks',
    region: 'us-east-1',
    prefix: 'orders',
  },
});

Until then: don't commit .sail/state.*.json to a public repo (it can contain endpoint URLs, secret ARNs, ECR refs — not the values themselves, but the references). The repo's .gitignore should include .sail/.

What's in the state file​

A simplified shape:

{
  "target": { "provider": "aws", "locator": "us-east-1" },
  "primitives": {
    "orders.database.orders": {
      "id": "arn:aws:rds:us-east-1:…:db:orders-orders",
      "attributes": {
        "endpoint": "orders-orders.xxx.us-east-1.rds.amazonaws.com",
        "port": "5432",
        "secretName": "orders/orders-credentials",
        "...": "..."
      }
    },
    "orders.webapp.web": { "id": "...", "attributes": { "...": "..." } }
  }
}

Keyed by URN (<project>.<type>.<name>). The provider populates id and attributes on every successful provision.

Adopt-on-existing​

If the state file is missing or doesn't list a primitive but the resource does exist in the cloud, providers adopt it. The deploy log will say [aws/database] adopting existing instance …. This is the recovery path when state was lost or the resource was created out-of-band; nothing gets duplicated.

Deleting state vs. deleting resources​

rm -rf .sail/ deletes only the local tracking. It does not delete your cloud resources — they'll keep running, and the next sail deploy will adopt them.

To delete cloud resources, use sail destroy. (See the CLI reference.)