# Recipes

URL: https://briq.cloud/docs/concepts/recipes

> Ready-made stacks that return connection strings, not Dockerfiles.

A **recipe** is a ready-made stack your agent asks for by name. It starts one or more briqs, waits
until they are healthy, and returns **outputs**: the connection strings and credentials your code
needs. Every recipe has a page in the [cookbook](https://briq.cloud/cookbook).

```text
briq_run({ recipe: "postgres" })
→ bq_7kq2m9x1p4ab db (postgres:16) running · …internal · cost so far … · sleeps at 18:42 UTC unless used
  outputs:
    DATABASE_URL=postgres://postgres:…@…internal:5432/app
    PGHOST=…internal
    PGPORT=5432
    …
```

* **Parameters** all have defaults, so the bare name always works. Pass them to change what you
  get: `params: { version: "17", extensions: ["pgvector"] }`.
* **Disk**: every recipe that keeps data takes `diskGb`, its volume's size. Defaults are small
  (1 to 5 GB); ask for what the data needs when you create it, `params: { diskGb: 20 }`, since the
  size is set then and counts toward your [plan's disk](https://briq.cloud/docs/cost#plans).
* **Secrets** are generated per run, returned once, and masked in status, logs and audit.
* **Outputs** are private addresses: they work as is from any briq in the team (use `briq_exec`,
  or run your code in a briq of the same [stack](https://briq.cloud/docs/concepts/stack)), not from outside.
* **`expose`** (`"private"`, or `"public"` for anyone) publishes the recipe's front door, when it has
  one (a dashboard, a wiki), and adds `URL` to the outputs. Databases have none, and asking fails.

Over REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "recipe": "postgres", "params": { "version": "17" } }'
```

`briq_catalog` (or `GET /v1/recipes`) lists every recipe; with a name (`GET /v1/recipes/{name}`),
every parameter it takes, with its default and what it does, and its outputs.

## Recipe or image?

Use a recipe when one fits: you get the healthcheck, credentials and connection strings for free.
Your own code runs on a [language recipe](https://briq.cloud/docs/guides/run-your-own-app), with no image to build.
Otherwise pass any image to `briq_run` with its own `env`, `ports`, `files`, `volume` and
`healthcheck` ([spec](https://briq.cloud/docs/concepts/briq#a-briq-spec)).