Run n8n on MIOSA

What you're building

a source-available workflow-automation platform with a native AI agent node and standalone agents Modelled on n8n, by n8n GmbH.

You build a workflow visually (or in code) from triggers and nodes; the AI Agent node reasons over tools, memory and a knowledge base, and standalone agents run with sub-agents, channels and schedules.

Primitives you'll use: Sandbox · Postgres · Redis

• Visual workflows that can drop into code
• An AI Agent node with tools, memory and knowledge
• Standalone agents with sub-agents and schedules
• Human-approval steps and per-run history

You install and run the real n8n on MIOSA. Read the official docs first: docs.n8n.io/hosting/installation/npm/. Every install command below comes from them; if the docs and this guide disagree, the docs win. n8n is source-available (Sustainable Use License); you self-host it.

What you need on MIOSA

Each row is one thing to create before you start. The number matches the step that uses it.

1. 1 Organization and API key Scopes every call; a workspace key is all a worker needs. miosa api-key create app-key --preset agent Docs
2. 2 Sandbox The isolated Linux workspace the agent writes code and runs commands in. miosa create app-box --template nextjs --wait Docs
3. 2 Postgres Managed relational data, injected as DATABASE_URL in the machine and in production. miosa api POST /databases -d '{"name":"app-db","engine":"postgresql"}' Docs
4. 2 Redis Managed cache and session store, injected as REDIS_URL. miosa api POST /databases -d '{"name":"app-cache","engine":"redis"}' Docs
5. 2 A workspace per customer Isolates each customer’s machines, deployments, and data as they onboard. miosa workspace create customer-1 Docs
6. 2 Branding and white-label Your name and slug on previews, deployments, and the desktop; customers never see MIOSA. miosa org Docs
7. 2 Usage metering and bill-to Usage per customer, and which account pays for new machines. miosa org bill Docs

Architecture

How it runs on MIOSA

Where it runs -> a MIOSA sandbox (an isolated Linux workspace)

State and files -> Workflows, credentials and execution history live in the n8n database; point n8n at managed Postgres so they survive a pause.

Model -> your own provider key, never a MIOSA platform key

Its web port 5678 -> a MIOSA preview URL (`miosa preview create`)

Your customers -> one workspace each, isolated from each other

Auth and tenancy

Your organization is the platform; customers never get a MIOSA account, they sign into YOUR product. One workspace per customer, created as they onboard, isolates their machines, runs and data.

miosa workspace create n8n-customer-1

Tag every machine and run with the customer id in `metadata`, and never query across customers. Meter usage per customer with GET /api/v1/usage and set who pays with PUT /api/v1/bill-to (/docs/platform/usage-and-billing).

Install n8n

Run these inside the sandbox (for example `miosa exec n8n-box -- bash -lc '<command>'`), in order. The commands are from the official docs.

node --version   # Node.js 20.19 or later (22.12+ is best) is required

npm install -g n8n

Check: the install finishes without errors; the next sections configure and start it.

Configure

Set your own model provider key in the n8n UI (Credentials) for the AI Agent node; MIOSA platform keys are never used.

Queue mode needs Redis and Postgres: create them in the workspace, then set DB_TYPE=postgresdb, DB_POSTGRESDB_* and QUEUE_BULL_REDIS_* before you start.

Model: Anthropic (Claude). Calls use my own provider key (ANTHROPIC_API_KEY); MIOSA platform keys are never used.

export ANTHROPIC_API_KEY="..."   # set it in the process environment, or the Secrets API; never write it into files you commit

Run it

Start it and prove it works.

n8n start

Scripted, non-interactive use (what a product or a queue would call):

n8n execute --file workflow.json   # run one workflow without the editor

Check: a headless task completes and prints a result.

Persistence and access

Workflows, credentials and execution history live in the n8n database; point n8n at managed Postgres so they survive a pause.

It listens on port 5678. Run it as a background process so it outlives your shell, then open a preview:

miosa preview create n8n-box 5678 --name web

Check: the preview URL answers, and still answers after the machine pauses and resumes (previews wake it on request).

Make it a product

Run one n8n per customer workspace, keyed to that customer's Redis and Postgres, behind your own login; meter executions per customer.

Limits and costs

Pin the version you tested and update deliberately; these tools change quickly.

Give the tool only the credentials it needs, as secrets, not baked into files.

Prototype: keep it to one machine at the default size, skip replicas and custom hostnames you do not need, and delete everything when you are done.

Acceptance checks

n8n runs on a MIOSA sandbox and answers a real task.

State survives a pause and resume.

Each customer has its own workspace and its own instance; nothing is shared between them.

Everything it created can be deleted with nothing left running.

Next steps

• Agent prompt builder Pick a product shape and hand the brief to your agent.
• Run coding agents Run Claude Code, Codex or Cursor in the cloud, or build a product on them.
• Compare MIOSA How MIOSA compares to other sandbox and agent platforms.
• What you can build Every product pattern MIOSA supports.