A backend program rarely works alone. It might store records in PostgreSQL, read an API key, or send work to another process. Each dependency raises the same practical questions: where does it run, how does the program reach it, and what may the program do with it?
Fluffy lets you describe those relationships explicitly. It uses that description to generate clients and prepare the services your program needs, locally or in your cloud project. You still write the program and decide what it does.
#Understand the pieces
#A runtime is a running program
An API and a background worker are two examples of runtimes. They can use different resources and have different permissions, even when they belong to the same application.
To run a program, Fluffy needs something it can execute. An artifact describes what to build or acquire. For a runtime, the build produces an OCI image archive containing the program and its dependencies. The runtime refers to that artifact. Two runtimes can use the same image while keeping separate access contracts; startup behavior belongs to the image.
#An application owns a set of relationships
An application groups runtimes, resources, and browser entrypoints in a fluffy-chainsaw.yaml file. It is also a deployment boundary: one workspace can contain applications that you deploy separately.
A resource declaration says the application needs something. A runtime's uses section says which resource that runtime may access and which actions it needs. Declaring a database does not give every runtime permission to query it.
For example, an API might read a database while a worker reads and writes it. Both refer to the same logical database, but their access differs. Try changing these relationships in How access works.
#A workspace decides where things belong
An application says what it needs. A workspace supplies the environment and provider policy used to satisfy those needs.
The workspace manifest, fluffy-chainsaw.workspace.yaml, names child directories and defines providers, resource types, and environments. A provider identifies a cloud project and region. A resource type selects a product and its settings. An environment chooses which policy applies to a particular run or deployment.
For example, an application can ask for a PostgreSQL server while workspace policy chooses Cloud SQL and its size. The application does not have to repeat those provider settings for every database.
#The SDK connects your code to that description
An SDK is a package your code imports. Fluffy generates a separate package for each runtime or browser entrypoint. A runtime's package reflects its declared access: a bucket read grant produces methods for reading that bucket.
A sidecar is a Fluffy process that runs beside the backend. Generated runtime clients call it over gRPC. It connects the logical operations in the SDK to the configured provider and enforces the deployed contract.
For objects and secrets, portable operations pass through the sidecar. For PostgreSQL, the sidecar supplies connection information and credentials; your normal SQL driver makes the database connection and runs queries. Fluffy does not turn database rows into generated application models.
#The browser has a different boundary
A web entrypoint serves browser assets and exposes selected backend services. The browser's generated SDK can call those services and use configured authentication. It cannot import private runtime clients or receive database credentials.
Your backend must still authorize the user behind each request. A grant allowing the API to read a file does not decide which people may download it.
#Configure the description
You work with two main files:
| File | What you decide there |
|---|---|
fluffy-chainsaw.yaml | Application name, artifacts, runtimes, resources, grants, browser exposure |
fluffy-chainsaw.workspace.yaml | Explicit child directories, environments, provider placement, reusable resource types |
Run Fluffy at the directory containing the workspace manifest. This is the exact invocation root: Fluffy follows declared children and does not search parent directories for a workspace. Running the same command from an application subdirectory can therefore select a different workspace or fail to find one.
You do not need a cloud project to understand these files or run the local example. Start guide provides an existing application you can build and run. Manifest reference explains the available fields.
#Follow a change through the system
- Edit the application declaration or workspace policy.
- Generate the affected SDK if the code-facing contract changed.
- Update your application to use that contract.
- Run locally and exercise the behavior.
- Preview the selected cloud environment, inspect the proposed change, then deploy it.
Each step has a different job. Generation writes client code. A preview describes proposed infrastructure changes. Deployment applies them and starts the application. None of those steps writes your business logic for you.
#Reference: boundaries that matter
| Situation | Fluffy's behavior |
|---|---|
| A resource exists but a runtime has no grant | That runtime receives no client for it |
| A grant exists but application code never calls its methods | No application request is made; strict source validation can reject provably unused grants |
| Several runtimes share an artifact | Each runtime still has its own access contract |
| An application runs locally | Local products supply the portable capabilities; local persistence is not cloud backup or high availability |
| An application deploys to GCP | Workspace policy resolves resources to supported products such as Cloud Run and Cloud SQL |
| A native provider operation is required | Use a supported native escape hatch and inspect its authority and local support |
| Premium is installed | Its features are available for configuration; installation alone does not grant a runtime extension capabilities |
Core owns manifests, client generation, local execution, and deployment. Premium adds customer services such as private previews and temporary human access. They build on the same application model.
Your GCP project owns the deployed infrastructure and operational data. Cloud deployment includes shared foundation infrastructure and separate application stacks. Learn that lifecycle in Deploy to GCP; explore client generation next in How access works.