# Why not run n8n itself inside a Docker Sandbox?

> Source: <https://www.ajeetraina.com/why-not-run-n8n-itself-inside-a-docker-sandbox/>
> Published: 2026-11-22 15:07:19+00:00

**Recommendation:** Run internet-facing automation services like n8n inside a Docker Sandbox microVM with deny-by-default egress, granting only the specific hosts each workflow needs via sbx policy allow network.
More in the playbook "Securing agents and AI tools": <https://wpnews.pro/playbooks/agent-security>

# Why not run n8n itself inside a Docker Sandbox?

If a Docker Sandbox can safely isolate an AI agent running arbitrary code, why not run a long-lived service like n8n in one too? n8n's whole job is reaching out to the internet with secrets attached exactly what you'd want on a leash.

[Docker Sandboxes exist](https://docs.docker.com/ai/sandboxes/?ref=ajeetraina.com) to run [**AI coding agents**](https://docs.docker.com/ai/sandboxes/agents/?ref=ajeetraina.com) (Claude Code, Codex, Copilot, Gemini) inside disposable microVMs with [credential proxying](https://www.ajeetraina.com/how-secrets-work-in-docker-sandboxes-local-vs-cloud/) and [network-policy enforcement](https://docs.docker.com/ai/sandboxes/security/defaults/?ref=ajeetraina.com). That's the headline use case. But a sandbox isn't an "agent runner"; it's a microVM with a declarative capability model. Once you see it that way, an obvious question falls out:

If a sandbox can safely box in an AI agent that runs arbitrary code, why *not* run a long-lived service like **n8n** inside one too?

n8n is workflow automation. Its whole job is to reach out to the internet (HTTP Request nodes, API integrations, webhooks), often with credentials attached. That is exactly the kind of thing you'd like to keep on a leash. A Docker Sandbox gives it one: [microVM isolation](https://www.ajeetraina.com/where-is-the-human-in-the-loop-a-map-of-approval-points-across-dockers-ai-tools/), a deny-by-default egress proxy, and ports/volumes you declare instead of improvise.

This post walks through packaging n8n as a **v3 workload kit**, what the sandbox buys you, and the one sharp edge that will trip you up on day one if nobody warns you (so: consider yourself warned).

## What a sandbox gives n8n

Running `docker run n8nio/n8n` on your laptop gives n8n your whole network. A sandbox inverts that:

- **microVM isolation:** n8n runs in its own kernel, not sharing yours.
- **Egress through a proxy, deny-by-default:** the sandbox's only way out is an HTTP/HTTPS forward proxy with TLS interception. A workflow can't quietly phone home to a host you didn't allow. You grant hosts explicitly:`sbx policy allow network api.github.com` .
- **Declared ports:** n8n's editor on`5678` is forwarded to an ephemeral`localhost` port, nothing more.
- **Declared, persistent storage:** workflows, credentials and the encryption key live on a named volume that survives stop/recreate.

For a tool whose job is "call lots of external systems with secrets," that's a very natural fit.

## The kit: a v3 *workload*, not an agent

A sandbox kit is one descriptor file. The interesting decision is the very first one: **n8n is a service, not an agent.** An agent kit declares the `sbx@1` capability, which tells the host "replace the image's entrypoint with an agent launcher and attach me a shell." n8n doesn't want that. It wants its own server to run. So the kit deliberately **omits `sbx@1`** and instead composes a handful of plain capabilities:

```
# n8n.yaml (excerpt)
schemaVersion: "3"
kind: workload
displayName: n8n

capabilities:
  # Keep the microVM alive after the launching client detaches.
  # n8n is a server, not a session, so auto-stop would kill running workflows.
  - type: com.docker.sandbox/long-running@1

  # sbx runs a keepalive as PID 1 and does NOT auto-start the image entrypoint
  # for a detached workload, so we launch n8n explicitly on every boot.
  - type: com.docker.sandbox/lifecycle@1
    config:
      interactive: [/bin/sh]          # the n8n image is Alpine, no bash
      startup:
        - command: [sh, -c, "chown node:node /home/node/.n8n"]
          user: "0"
          background: false
        - command:
            - sh
            - -c
            - >
              export N8N_SECURE_COOKIE=false N8N_PORT=5678
              N8N_LISTEN_ADDRESS=0.0.0.0;
              exec /usr/local/bin/n8n start >>/home/node/.n8n/n8n.log 2>&1
          user: node                   # the n8n image's uid-1000 user is `node`
          background: true

  # Editor / REST / webhook endpoint.
  - type: com.docker.sandbox/port@1
    config: { name: n8n-editor, container: 5678, transport: tcp }

  # Persist workflows, credentials and the encryption key.
  - type: com.docker.sandbox/volume@1
    config: { path: /home/node/.n8n, size: 2g, mode: "0755" }

  # Runtime egress: the editor boots fully offline; workflow targets are
  # granted at runtime with `sbx policy allow network <host>`.
  - type: com.docker.sandbox/network-policy@1
    config:
      runtime:
        allow: [api.n8n.io]
```

A few details that matter and are easy to get wrong:

- **The image is Alpine.** No`/bin/bash` . The startup hooks shell out with`sh` , and`interactive: [/bin/sh]` points interactive sessions at the shell that actually exists.
- **n8n runs as `node` (uid 1000), not `agent`.** The startup hook names` user: node` so the host doesn't try to`su agent` . One hook runs as root first, purely to`chown` the volume mount root before n8n touches it.
- **Settings are exported inline in the command.** The lifecycle config env is deny-by-default and startup hooks don't inherit image`ENV` , so the settings that must be right (`N8N_LISTEN_ADDRESS=0.0.0.0` , etc.) are set in the command, and only the proxy vars are passed through by name.

The companion `n8n.dockerfile` is boring on purpose: `FROM docker.n8n.io/n8nio/n8n`, a build-time assertion that the installed n8n version matches the pin, and some runtime `ENV`. A workload kit's layers *are* the root filesystem, so it's an ordinary image build.

## Building and running it

```
# validate the descriptor (fast)
docker buildx build . -f n8n.yaml --output type=cacheonly

# build an OCI layout and run conformance (kit-tck)
docker buildx build . -f n8n.yaml -t n8n:2.47.7 \
  --output type=oci,dest=/tmp/n8n-layout,tar=false
kit-tck validate --layout /tmp/n8n-layout 2.47.7
```

Then run it from the published image:

```
sbx create --name n8n-demo docker.io/ajeetraina777/n8n:2.47.7
sbx ls | grep n8n-demo        # find the forwarded host port
```

You'll see something like `127.0.0.1:49154->5678/tcp4`. Open `http://localhost:49154`, complete the owner setup, and you have n8n running in a microVM. (Login works over plain HTTP because the image sets `N8N_SECURE_COOKIE=false`.)

## The sharp edge: `sbx run` vs `sbx create`

Here's the part that cost me an afternoon, and the reason this post exists.

The intuitive first command is `sbx run <image>`. It fails:

``` bash
$ sbx run docker.io/ajeetraina777/n8n:2.47.7
  ✓ Created sandbox n8n-1
  ○ n8n — starting in sandbox n8n-1…

chdir to `/home/agent`: No such file or directory
executable file `/bin/bash` not found: No such file or directory
  error: agent exited with code 127
```

That error is alarming and completely misleading. **The sandbox was created, the port was forwarded, and n8n started fine.** If you run `sbx ls` you'll see it sitting there `● running`. So what failed?

`sbx run` does two things: it *creates* the sandbox, and then it *attaches an interactive agent session* to your terminal. That attach is a generic agent launch: `chdir /home/agent`, `exec /bin/bash`. But this is a **workload** kit (no `sbx@1`): it's a detached background service. There is no agent to attach to, and the Alpine n8n image has neither `/home/agent` nor `/bin/bash`. So the attach dies with `code 127`, *after* everything you actually wanted has already succeeded.

The fix is simply to use the verb that doesn't attach:

```
sbx create --name n8n-demo docker.io/ajeetraina777/n8n:2.47.7
```

### Two more things to watch for

**`--name` does not mean detached.** After `create`, sbx helpfully prints `try: sbx run --name n8n-1`. Don't. `sbx run --name n8n-1` still attaches and still fails the same way. **Only `-d` skips the attach.** To resume a stopped workload:

```
sbx run -d --name n8n-demo     # always -d for a workload
```

**You can't rescue the attach from the kit (on current sbx).** The descriptor sets `interactive: [/bin/sh]` precisely so the attach would use a shell that exists. On the sbx I tested (`v0.54.0-rc7`), that field isn't honored for a non-` sbx@1` workload. The attach hardcodes `/home/agent` + `/bin/bash` regardless. So you simply never attach to this thing. When you want a shell, `exec` into it explicitly:

```
sbx exec -it n8n-demo /bin/sh   # runs as node; sh, not bash
```

### The rules, as a table

| Goal | Command | 
|---|---|
| Start | `sbx create --name n8n-demo docker.io/ajeetraina777/n8n:2.47.7` | 
| Resume after stop | `sbx run -d --name n8n-demo` (**always `-d`** ) | 
| Shell inside | `sbx exec -it n8n-demo /bin/sh` | 
| Find the current port | `sbx ls \ | 
| Never | bare {% raw %} `sbx run …` /`sbx run --name …` (no`-d` ): the attach fails with`127` | 

The mental model that makes all of this obvious: `sbx run` is for agents you sit in front of; `sbx create` (+ `exec`) is for services you leave running.

## Living with it

**Persistence.** Everything that matters (workflows, credentials, the encryption key) lives under `/home/node/.n8n` on the declared volume. Stop and resume freely; the data survives. Note the port is re-assigned on each resume, so re-check `sbx ls` after a restart rather than hardcoding `49154`.

**Letting workflows reach the internet.** The editor boots fully offline. The first time a workflow's HTTP Request node needs an external host, the egress proxy blocks it until you allow it:

```
sbx policy allow network api.github.com
sbx policy allow network "*.googleapis.com"
sbx policy log                 # see what was allowed / blocked
```

This is the feature, not a nuisance: your automation platform can only talk to hosts you've consciously approved.

**Public webhooks.** A sandbox forwards n8n to `localhost`, so externally delivered webhooks aren't reachable out of the box. The right place for a tunnel is **your host**, in front of the forwarded port, not inside the sandbox, whose only egress is the MITM proxy that a raw `cloudflared` QUIC connection can't traverse:

```
port=$(sbx ls | grep n8n-demo | grep -oE '127.0.0.1:[0-9]+' | cut -d: -f2)
cloudflared tunnel --url "http://localhost:$port"
```

Then point n8n's `WEBHOOK_URL` at the tunnel.

## So, why not?

Running n8n in a Docker Sandbox isn't a hack; it's the capability model working as intended. You get a reproducible, single-descriptor package (`sbx create .` and you're up), microVM isolation, and an egress allow-list that every workflow request has to pass through. That last one is the real win for an automation tool.

The cost is one unlearning: a sandbox's default verb, `sbx run`, assumes you want an interactive agent. A service doesn't. Reach for `sbx create` and `sbx exec` instead, keep `-d` on every resume, and ignore the `try: sbx run --name …` hint sbx prints. Do that and the alarming `code 127` you'll inevitably hit once becomes what it always was: a harmless attach to a service that was already happily running.

*The kit, Dockerfile, and a tag-triggered multi-arch publish workflow (cosign keyless signing included) live at* *github.com/ajeetraina/sbx-kits-n8n**. Tested with n8n `2.47.7` and `sbx v0.54.0-rc7`.*
