# n8n recipe

URL: https://briq.cloud/cookbook/n8n

> Workflow automation: webhooks, schedules and integrations (WhatsApp, Slack, Gmail…). The agent builds workflows with briq_exec ["node", "/briq/n8n-api.mjs", "POST", "/workflows", "-"]. Run it with expose: "public" so webhooks reach it.

Tags: app, automation

Guide:

- [Automate with n8n](https://briq.cloud/docs/guides/automate-with-n8n.md): Run n8n with a public URL for webhooks, then have the agent build, activate and test workflows through its API.

## Run it

briq.yaml:

```yaml
stack: app
services:
  n8n:
    recipe: n8n
    # its defaults, each a field you can set:
    # image: n8nio/n8n:latest
    # size: small
    # volume: { gb: 2 }
```

MCP:

```ts
briq_run({ recipe: "n8n", wait: true })
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "n8n",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "N8N_URL": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

## Fields

Set them beside `recipe`, in briq_run or a briq.yaml service, as a GitHub Actions service.

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `image` | string | — | "n8nio/n8n:latest" | The image: another tag, or a compatible image (as for a GitHub Actions service) |
| `env` | record | { key: string \| { secret, value?, scope?, hosts?, locations? } } | {} | Added to the recipe's env, or replacing one of its values. A credential as { secret: NAME, value } |
| `cmd` | string \| string[] | — | — | The command: a string run with sh -c, or the argv. Default: the recipe's |
| `size` | enum | small, medium, large | "small" | The machine size |
| `volume` | object | { gb? } | {"gb":2} | The volume: { gb } |
| `files` | record | { key: string \| { base64 } } | — | Boot files, added to the recipe's |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `N8N_URL` | `http://n8n.<stack>.internal:5678` |
| `N8N_OWNER_EMAIL` | `owner@n8n.local` |
| `N8N_OWNER_PASSWORD` | `<N8N_OWNER_PASSWORD>` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| n8n | `n8nio/n8n:latest` | 5678 | small | 2 GB at /home/node/.n8n |

## When to use it

* A process should run on its own when something happens: a WhatsApp message, a form, a payment,
  an email, a time of day.
* The work is mostly glue between services n8n already knows (WhatsApp, Messenger, Slack, Gmail,
  Sheets, Stripe), not code of your own.
* The agent builds the automation and a person checks it in n8n's editor.

[Automate with n8n](https://briq.cloud/docs/guides/automate-with-n8n) goes from the first call to a working webhook.

## Tips

* **Run it with `expose: "public"`**: n8n reads its URL at boot to print its webhook URLs, and a
  service that sends webhooks cannot pass a private URL's token. The editor has its own sign-in.
* **The agent calls the API with `node /briq/n8n-api.mjs METHOD PATH [JSON|-]`** in `briq_exec`.
  It signs in as the owner and keeps an API key on the volume.
* **The person signs in** with `N8N_OWNER_EMAIL` and `N8N_OWNER_PASSWORD` from the outputs.
  briq makes that owner before n8n starts, so no one else can claim the instance.
* **Credentials go in the editor** (Credentials → Add): n8n keeps them encrypted on the volume.
* **A schedule runs only while the briq is awake.** Webhooks wake it; a timer does not. Use
  `sleep: "never"` for a Schedule Trigger.
* **Another version**: `image: "n8nio/n8n:2.44.5"` pins it.
* **More room**: runs and their data are kept in SQLite on the volume (2 GB). Set `volume: { gb }`
  when the briq is created; it counts toward your [plan's disk](https://briq.cloud/docs/cost#plans).