Project environments

A project environment is a saved, prepared workspace. Statefold runs your setup once in a fresh workspace and saves the dependencies and build output it produced; every new thread in the project starts with them in place instead of installing from scratch.

Save an environment

Open Settings → Environments and pick a project.

• Setup command overrides the repository's .agents/setup. It runs once when the environment is saved, not in every thread. For example, bun install --frozen-lockfile.
• Start commands override .agents/services.yaml: one per line as name: command, for services a thread should start.

Choose Save as environment. While it saves you can read the setup output. When it finishes, the environment shows when it was saved, its commit and its size.

What is saved

• Ignored dependency folders such as node_modules, .venv, vendor, .gradle and package caches.
• Build output such as target, dist, build, .next/cache and .turbo, without files whose names suggest credentials.
• Ignored SQLite databases, as online backups.
• Whatever the repository's .agents/backup hook adds.

What is never saved

• Credentials: .env*, .dev.vars, cloud credential files and keys.
• Other threads' history.
• PostgreSQL data, unless your .agents/backup hook saves a PostgreSQL 16 base backup. Raw data directories are never captured. The hook must be executable; if it fails, the save fails.

Keeping it fresh

When lockfiles change after a save, the environment shows Needs refresh with the files that changed. Refresh saves it again. If a save fails, Retry it; threads keep using the previous environment meanwhile.

The tools already in every workspace are listed in Workspace tools.