Run locally

A local run gives your application real processes and local implementations of its declared dependencies. Your runtime still uses its generated SDK and its own grants. The provider behind that contract changes.

#Understand: what starts, and in which order

Fluffy builds the selected artifacts and sidecars, starts dependencies, applies database migrations, synchronizes local fixtures, runs seeds, and finally starts workloads. A failed lifecycle task stops startup: an API should not start against a database whose migration failed.

Local persistence lets you stop and resume development. It is not a backup. Local providers also do not reproduce every cloud-native API; each resource guide identifies the portable operations.

#Configure: start a workspace

Complete the source build and SDK setup. Check docker info and docker compose version, then run from the exact workspace root. Replace example-app with a declared application name:

fluffy-chainsaw local --application example-app --print
fluffy-chainsaw local --application example-app

The first command validates and prints the Compose template without creating local state or starting containers. The second starts the application. Open the URLs Fluffy prints; host ports are allocated, not assumed.

Omit --application to run the whole workspace, or repeat it for a subset. All applications referenced by a selected application's fluffy:// environment values must be selected too:

fluffy-chainsaw local --application marketing --application platform-web

#Choose application environment values

Local runs default to local: base env values merge with environments.local.env when that block exists. An application without it uses base values. An explicit override must exist in every selected application:

fluffy-chainsaw local --application example-app --application-environment dev

This selects application values while keeping local providers. It does not connect your runtime to the cloud resources of that environment.

#Add local data

Database migrations belong to the application manifest. Local seeds, authentication fixtures, and flag snapshots belong in fluffy-chainsaw.local.yaml beside it. For an existing auth declaration named users, this local fixture adds a test identity:

apiVersion: fluffy-chainsaw.dev/local/v1
auth:
  users:
    owner:
      email: owner@local.test
      emailVerified: true

Merge with existing local configuration. Keep seeds idempotent so another startup can safely run them. The database example supplies migration and seed code; authentication and flags explain their fixtures. Use test values: a broad build-context copy can include local files in an image.

#Run a frontend development server

Normal artifacts rebuild when source changes. A frontend can instead run an existing development-server script inside its pinned builder. For an artifact named web-assets with an npm dev script that accepts these flags:

apiVersion: fluffy-chainsaw.dev/local/v1
development:
  artifacts:
    web-assets:
      prepare: [npm, ci, --ignore-scripts]
      command: [npm, run, dev, --, --host, 0.0.0.0, --port, "3000", --strictPort]
      port: 3000
      persistentDirectories: [node_modules]

The dev process owns source reloads. Fluffy proxies HTTP and WebSockets and preserves the browser deployment-document endpoint. This excerpt requires that script and artifact to exist; it does not create either one.

#Stop, resume, or discard data

The terminal dashboard lists services, URLs, and ports. Arrows or j/k select a service, Enter opens logs, and e opens refresh events. Use q or Ctrl-C to stop. Redirected output uses plain progress messages.

Restart normally to reuse local state. Use an ephemeral run when this session should be disposable:

fluffy-chainsaw local --application example-app --ephemeral

To intentionally remove selected persisted data, first stop its local run:

fluffy-chainsaw local reset --application example-app

Reset asks for confirmation. Noninteractive reset requires --yes. --workspace selects all applications and cannot be combined with --application.

#Reference: diagnose the failing stage

Reset removes data; it does not fix source errors. Inspect the failing service's logs first. The CLI reference lists selectors and reset options. Continue with deployment when a local application operation succeeds.