Import an n8n workflow
This walkthrough imports a workflow exported from n8n — an AI agent answering chat messages with an OpenAI chat model and a memory — into an Aggregate, a Release and a Manifest that build n8n carrying the workflow for Docker Compose as they are written, then builds them and runs the result. Every file and every block of output below comes from a real run; the workflow and each stage of the walkthrough are in the import-n8n example, where a check script runs the import again, compares what it writes, what it prints and the blocks this page quotes with the files kept there, and validates and builds what the import wrote.
Scaffold the example
You can run this import with the commands on this page, or have your AI assistant run it for you.
Write the example into a new folder named after it:
aggrega scaffold --example import-n8nIt then prints the commands to run next. The first changes into the new folder;
the one after it, below, changes into its source folder, which holds what this
page imports and is where the import runs:
cd import-n8n
The workflow
support-agent.json, written for this walkthrough in the shape n8n exports a
workflow, holds four nodes: a chat trigger, an AI Agent with a short system message, an OpenAI Chat Model node
selecting gpt-4o-mini, and a Simple Memory node, joined by the connections
n8n lists by the name of the node each leaves. The chat trigger is public, so a
chat message sent to its URL starts the workflow, and it asks the sender for a
user and password, which it checks against a basic-authentication credential
n8n stores:
"parameters": { "public": true, "authentication": "basicAuth", "options": {} }, [… omitted: the node's identifier, name, type, version, position and webhook identifier] "credentials": { "httpBasicAuth": { "id": "Vx3mQ8rLb2Nk7Tz5", "name": "Chat basic auth" } }The model node selects its credential the same way, by reference — the export carries each credential’s identifier and name, never the user, the password or the key:
"parameters": { "model": { "__rl": true, "value": "gpt-4o-mini", "mode": "list", "cachedResultName": "gpt-4o-mini" }, "options": {} }, "id": "6f1d2c3a-7b4e-4a8f-9c21-0d3e5f6a7b03", "name": "OpenAI Chat Model", "type": "@n8n/n8n-nodes-langchain.lmChatOpenAi", "typeVersion": 1.2, "position": [120, 220], "credentials": { "openAiApi": { "id": "Rb7nW2xQ9kT4mZ1c", "name": "OpenAI account" } }Beside the workflow, an .aggrega-config.yaml makes the folder a workspace:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside support-agent.json.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiand import-answers.yaml holds the answers to what no workflow can hold. An
import for Docker Compose needs none: it attaches the OpenAI key by a variable
reference Docker Compose fills from your shell. An import for Kubernetes
attaches it by the name of a Kubernetes Secret, which only you can name, so the
file names that Secret (see On Kubernetes):
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.n8n.uses.model.openai-chat-model.features.credential.infra.origin: "openai-api-key"The import answers file describes the file in full.
The import weighs each node against the Components of the workspace’s catalog,
and --target drafts a Manifest from its Recipes. The workspace names no
catalog folder, so the import reads the standard-library catalog from the
registry it fetches its importer from: a signed snapshot of the published
catalog, fetched, verified and kept in the workspace’s content cache by the
first import, and named by its digest in the record the import writes beside its
drafts. A workspace that names its own catalog folders — in
AGGREGA_CATALOG_DIRS, or under workspace.catalog_dirs — imports against
those instead. Change into source:
cd sourceRun the import
aggrega import support-agent.json --target composeOn standard output it lists what it wrote:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonOn standard error, with <workspace> standing for the folder you ran it in:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the n8n format, with drafted paths relative to <workspace>warn: the value of credentials.httpBasicAuth.id of node When chat message received is carried as written in the flow the draft carries: its format marks the field as a credential, and setting empty_credentials to marked or all writes it emptywarn: the value of credentials.openAiApi.id of node OpenAI Chat Model is carried as written in the flow the draft carries: its format marks the field as a credential, and setting empty_credentials to marked or all writes it emptywarn: node OpenAI Chat Model reaches openai-chat-model, wired to the model socket of core/ai-agent/n8n as openai-chat-model, other than through that connection: an n8n @n8n/n8n-nodes-langchain.lmChatOpenAi node reaches the part at the address the stored credential it selects, or its own parameters, give; the platform delivers this connection as OPENAI_BASE_URL and OPENAI_API_KEY, but an n8n workflow reads a variable of the platform's environment only through an expression reading $env, which the platform refuses while values.allow_env_access_in_nodes is false, the value the draft leaves it at; setting it true lets every workflow, and every user who can edit one, read every variable of the platform's environment, the delivered credentials includedmade no choice for When chat message received (@n8n/n8n-nodes-langchain.chatTrigger)made no choice for AI Agent (@n8n/n8n-nodes-langchain.agent)mapped OpenAI Chat Model (@n8n/n8n-nodes-langchain.lmChatOpenAi) to core/ai-model/openai as a reference, HIGH at 0.9143made no choice for Simple Memory (@n8n/n8n-nodes-langchain.memoryBufferWindow) warning: node "n8n" (provider "compose"): artifact "n8n-flow.compose-fragment.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set.Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- The
mappedline says the OpenAI Chat Model node became the standard library’s OpenAI model,core/ai-model/openai, referenced rather than drafted, since it matched in the high tier, at 0.9143: a component of its own, wired to the platform’smodelsocket. - The
made no choicelines say that the trigger, the agent and the memory stay inside the workflow, which n8n runs itself. - The first two
warnlines name the identifiers of the stored credentials the trigger and the model node select, which n8n marks as credentials. They are references, not secrets, and they are carried as written. - The third
warnline is the one to read closely: the model node reaches OpenAI with the stored credential it selects, not through the connection the draft wires. The platform delivers the connection to n8n’s environment, and n8n refuses a workflow’s reads of its environment while the Aggregate leavesvalues.allow_env_access_in_nodesatfalse, as the draft does. Setting ittruelets every workflow, and everyone who can edit one, read every variable of the platform, the delivered key included. So the key the workflow uses is the one n8n stores, as Run it shows. - The last two lines are the pull. Nothing was left to answer, so the import
pulled the drafted Release’s dependencies, as
aggrega pulldoes, and wroterelease.lock; the build below needs nothing more. Thewarningline is one the build prints too, and Validate and build explains it.
The answers file names a Secret this import does not ask for: it leaves nothing empty for it, so it applies no answer and leaves the file as it is.
What it writes
The Aggregate, the Release and the Manifest are named
imported/support-agent, after the workflow’s own name, Support agent,
reduced to support-agent — a workflow with no name is named after its file —
under the namespace the importer’s target_namespace setting sets, imported
unless you set another
(Settings).
aggregate.yaml — one instance of the standard library’s n8n platform,
core/ai-agent/n8n, carrying the workflow as it was exported, most of it left
out here, and the model wired to its model socket:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/support-agent version: 0.1.0 description: Draft Aggregate imported from a source in the n8n format.spec: components: n8n: type: core/ai-agent/n8n values: workflow_id: 'sQ4vT8nKp2LmX7bR' flow_definition: | { "id": "sQ4vT8nKp2LmX7bR", "name": "Support agent", [… omitted: the rest of the workflow, as exported] } uses: model: openai-chat-model: target: openai-chat-model # For the compose target, the lines below declare credential on openai-chat-model: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. features: credential: type: core/secret-value values: key: OPENAI_API_KEY # swap to core/ai-model/azure-openai (score 0.4125) by setting type: core/ai-model/azure-openai openai-chat-model: type: core/ai-model/openai values: model: |- gpt-4o-miniworkflow_id is the identifier the export gives the workflow. The model is
core/ai-model/openai, with the model the node selects, gpt-4o-mini; the
comment above it names another Component of the catalog the node resembles,
with its score. The OpenAI key the platform presents to the model is declared
on the connection with the variable it arrives under in n8n’s environment,
OPENAI_API_KEY; the Release says where it comes from.
release.yaml — the Release, which deploys the Aggregate with the Manifest:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/support-agent # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the n8n format.spec: aggregate: imported/support-agent manifest: imported/support-agent components: n8n: infra: # The image running core/ai-agent/n8n, at the version this importer drafts, which the catalog's Recipes for it are known to run; the import does not raise or lower it to follow the source. image: "n8nio/n8n:1.110.1" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 5678 uses: model: openai-chat-model: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential n8n presents to openai-chat-model on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" openai-chat-model: {}environmentisdevelopment, a default the comment above it says to change to the environment the Release deploys to.- The image is n8n 1.110.1, the version the catalog’s Recipes for n8n run.
published_portis 5678, the port n8n serves on, so the editor answers athttp://127.0.0.1:5678on your machine. As its comment says, any process on this machine can reach it there and nothing else can; delete the line to keep n8n on the stack’s network alone. Apublished_portother than 5678 needsinfra.external_base_url: http://127.0.0.1:<published_port>beside it, or n8n reports its editor and webhook addresses onlocalhost:5678.- The key is a variable reference,
${OPENAI_API_KEY}, which Docker Compose fills from your shell when the stack starts. The standard library’s OpenAI model is a hosted service, and a connection to it must carry a credential, so the Release attaches one even though the workflow reads its key from n8n’s store.
manifest.yaml — the Compose Recipes of the platform and the model, and the
realization that writes the key’s variable reference into the Compose file as
written:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/support-agent version: 0.1.0spec: mappings: components: type: core/ai-agent/n8n: compose/n8n core/ai-model/openai: compose/openai features: type: core/secret-value: compose/dotenv-secret.aggrega-import.json is the record of what the import wrote, which a later
aggrega import --sync reads, and release.lock pins every catalog entity the
Release resolves to, by version and digest.
Validate and build
aggrega validate --release release.yamlaggrega build --release release.yaml

The validation prints:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)and the build, with <workspace> standing for the folder holding the drafts:
warning: node "n8n" (provider "compose"): artifact "n8n-flow.compose-fragment.yaml": skipped provenance label injection — the fragment declares no compose service. Compose carries build provenance as service labels, so a fragment contributing only top-level networks, volumes or configs carries none; the services this component emits elsewhere carry the full set. notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distThe warning line is about the part of the Compose file that carries the
workflow, a top-level configs entry, which has no service to put the build’s
labels on. The notice line is advisory: the secret Feature accepts its
origin from the Aggregate’s values or the Release’s infra, and the notice
reports that one leaf is declared in both. Neither changes the verdict.
dist/compose/docker-compose.yaml holds n8n and a service that imports the
workflow before n8n starts:
services: n8n: image: n8nio/n8n:1.110.1 environment: OPENAI_BASE_URL: https://api.openai.com/v1 OPENAI_API_KEY: ${OPENAI_API_KEY} N8N_BLOCK_ENV_ACCESS_IN_NODE: "true" ports: - 127.0.0.1:5678:5678 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] volumes: - type: volume source: n8n--data target: /home/node/.n8n networks: - compose depends_on: n8n--import-flow: condition: service_completed_successfully [… omitted: the service's health check] n8n--import-flow: image: n8nio/n8n:1.110.1 command: - import:workflow - --input=/flows/workflow.json entrypoint: - n8n [… omitted: the labels the build writes on every service] volumes: - type: volume source: n8n--data target: /home/node/.n8n networks: - compose restart: "no" configs: - source: n8n-flow target: /flows/workflow.jsonThe workflow reaches n8n through n8n import:workflow, run on the same data
volume each time the stack starts, before n8n itself. N8N_BLOCK_ENV_ACCESS_IN_NODE
is "true", n8n’s block on a workflow reading its environment, since the
Aggregate leaves allow_env_access_in_nodes at false. So the OpenAI Chat
Model node reads its key from n8n’s own credential store, as the chat trigger
reads its user and password, and the run below stores both. n8n’s Compose
Recipe publishes a port on your machine only where the Release sets
published_port in n8n’s infra, and then on the loopback address,
127.0.0.1, alone; without it, the service is reached on the stack’s network
only.
With an AI assistant
An AI assistant set up with Aggrega’s tools can do the same: paste this prompt into it.
Use the Aggrega tools only, and create no folder yourself. If the Workspace folder holds no `import-n8n` folder yet, call the `scaffold` tool once with `example` set to `import-n8n` and no `dir`: it writes the example into a new `import-n8n` folder, whose `source` folder holds what this page imports. Then call the `import` tool with `workspace_root` set to `import-n8n/source`, `source` set to `support-agent.json` and `target` set to `compose`: it reads the answers it needs from `import-answers.yaml` beside `support-agent.json`, writes its drafts into `import-n8n/source` and pulls what they need. Then call the `validate` tool with `workspace_root` set to `import-n8n/source` and `release` set to `release.yaml`, and the `build` tool with `workspace_root` set to `import-n8n/source`, `release` set to `release.yaml` and `write` set to true. Tell me which files the build wrote; they are under `import-n8n/source/dist/`.Open it in VS Code
With the
Aggrega extension for Visual Studio Code
installed, open the folder import-n8n/source in VS Code, where the import
wrote its drafts. The folder holds one Release, the drafted release.yaml, so
the editor selects it for you, and it checks the drafts against that Release as
you edit them, marking what it finds in the file and in the Problems panel.
Aggrega: Show topology graph, in the Command Palette, draws the Release’s
components and the connections between them. Aggrega: Build,
Aggrega: Preview build and Aggrega: Pull act on the same Release, and
each is also a button on the Commands panel of the Aggrega view in the
activity bar; Build writes its files into the folder’s dist/.
Use Aggrega in Visual Studio Code covers the rest.
Run it
n8n reads both credentials the workflow selects from its own store, by their
identifiers: the OpenAI key under Rb7nW2xQ9kT4mZ1c, and the chat’s user and
password under Vx3mQ8rLb2Nk7Tz5. n8n’s own command line stores them, under
those identifiers, from a file. Write them into credentials.json, with your
own values:
[ {"id": "Rb7nW2xQ9kT4mZ1c", "name": "OpenAI account", "type": "openAiApi", "data": {"apiKey": "your OpenAI key"}}, {"id": "Vx3mQ8rLb2Nk7Tz5", "name": "Chat basic auth", "type": "httpBasicAuth", "data": {"user": "a user of your own", "password": "a password of your own"}}]Set the key in your shell, as the drafted Release reads it, and start the stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p support-agent -f dist/compose/docker-compose.yaml up -d --wait-p names the project, as the run step of
How an import runs explains. --wait returns
once n8n reports healthy, after the service importing the workflow has run and
exited. Copy the credentials into n8n’s container, import them, and remove the
copy:
docker compose -p support-agent -f dist/compose/docker-compose.yaml exec -T n8n sh -c 'umask 077; cat > /tmp/credentials.json' < credentials.jsondocker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n n8n import:credentials --input=/tmp/credentials.jsondocker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n rm /tmp/credentials.json[… omitted: n8n's notices about its settings file's permissions, error tracking and deprecated settings]Successfully imported 2 credentials.n8n holds both credentials now, so delete credentials.json:
rm credentials.jsonThen activate the workflow, and restart n8n so the activation takes:
docker compose -p support-agent -f dist/compose/docker-compose.yaml exec n8n n8n update:workflow --id=sQ4vT8nKp2LmX7bR --active=truedocker compose -p support-agent -f dist/compose/docker-compose.yaml restart n8nOnce docker compose -p support-agent -f dist/compose/docker-compose.yaml ps n8n
shows n8n (healthy) again,
docker compose -p support-agent -f dist/compose/docker-compose.yaml logs n8n
reads Activated workflow "Support agent" (ID: sQ4vT8nKp2LmX7bR).
Test it
Open http://127.0.0.1:5678, the address published_port publishes: n8n’s
editor asks for an owner account on its first visit, then shows Support agent.
The chat trigger takes a message only with the user and password stored
above; without them it answers HTTP/1.1 401 Unauthorized and
Authorization is required!, and with a wrong password HTTP/1.1 403 Forbidden.
With the two in CHAT_USER and CHAT_PASSWORD, curl reads them from its
standard input, so they appear on no command line:
printf 'user = "%s:%s"\n' "$CHAT_USER" "$CHAT_PASSWORD" | curl --config - -sS -i -X POST \ http://127.0.0.1:5678/webhook/a3c9e1f2-4b5d-4e6f-8a7b-9c0d1e2f3a04/chat -H 'Content-Type: application/json' \ -d '{"action": "sendMessage", "sessionId": "s1", "chatInput": "In one short sentence: what does a support plan cover?"}'HTTP/1.1 500 Internal Server Error[… omitted: the response's other headers]
{"message":"Error in workflow"}The run stored a placeholder for the OpenAI key, so the workflow stopped at
its call to the model. n8n keeps the execution, which the editor lists under
the workflow’s executions, with OpenAI’s refusal:
Incorrect API key provided: sk-place*****************-key. With your key,
the reply is HTTP/1.1 200 OK and the agent’s answer, as {"output": "…"}.
On Kubernetes, with the build On Kubernetes describes
applied, n8n keeps its data in a volume that lives as long as its pod, so a
new pod starts without what you stored; store the credentials and activate the
workflow on the running instance instead. Write credentials.json as
Run it does, import it through kubectl exec, from its standard
input, in the namespace you applied to, and delete it afterwards:
kubectl exec -i -n <namespace> deploy/n8n -- n8n import:credentials --input=/dev/stdin < credentials.jsonDefaulted container "main" out of: main, import-flow (init)[… omitted: n8n's notices about its settings file's permissions, error tracking and deprecated settings]Successfully imported 2 credentials.Forward a local port to n8n’s Service, n8n-default, and leave the command
running:
kubectl port-forward -n <namespace> svc/n8n-default 5678:5678From another terminal, set up the owner account through n8n’s API, which signs
you in and keeps the session in cookies.txt, then activate the workflow:
curl -sS -c cookies.txt -X POST http://127.0.0.1:5678/rest/owner/setup -H 'Content-Type: application/json' \ -d '{"email": "owner@example.com", "firstName": "Your", "lastName": "Name", "password": "a password of your own"}'curl -sS -b cookies.txt -X PATCH http://127.0.0.1:5678/rest/workflows/sQ4vT8nKp2LmX7bR \ -H 'Content-Type: application/json' -d '{"active": true}'The second reply is the workflow, with "active":true. The
chat message above then reaches it at the same address, unchanged; the run got
the same {"message":"Error in workflow"} and the same refusal in the
execution.
Stop the stack with the command below. -v also removes n8n’s data volume, and
with it the stored credentials and the activation:
docker compose -p support-agent -f dist/compose/docker-compose.yaml down -vOn Kubernetes
The same workflow imports for Kubernetes with the helm target. The drafts
for Docker Compose already sit in source, and the import never writes over
an Aggregate there, so draft these into a folder of their own with
--output-dir, then validate and build from it:
aggrega import support-agent.json --target helm --output-dir helmcd helmaggrega validate --release release.yamlaggrega build --release release.yamlThe drafts differ where the target does. The Manifest maps the platform to
helm/n8n, the model to helm/openai, and the key to
helm/k8s-existing-secret, which reads it from a Secret already in the
namespace. The Release attaches the key as core/referenced-secret, naming
that Secret, openai-api-key, from the answers file.
The build writes plain Kubernetes manifests under dist/helm/ at the
workspace root, source, which from helm is ../dist/helm/. Create the
Secret in the namespace you apply to, holding the key under the data key
value, then apply the folder as the run step of
How an import runs explains. The workflow still
reads its credentials from n8n’s own store, which Test it fills on
Kubernetes.