n8n-sandbox-runner

n8n-sandbox-runner

Docker app from benjaminmue's Repository

Overview

Runner for the self-hosted n8n code sandbox. Only useful together with an existing n8n container and the n8n-sandbox-api container: install n8n-sandbox-api first and follow the setup steps in its description. The runner does the actual work. It runs its own Docker engine (Docker-in-Docker) and starts one throwaway container per sandbox, in which the n8n Assistant and n8n Agents run AI-generated code. It registers with n8n-sandbox-api over mutual TLS, using the certificates n8n-sandbox-api created on its first start. It restarts on its own until n8n-sandbox-api is reachable, so the start order does not matter. The first start takes longer because the inner Docker engine is set up first; until the runner has registered, n8n reports "no sandbox runners are registered or available". Privileged: Docker-in-Docker requires it. Treat this container as root on the host. It publishes no ports; keep it that way and never expose it to the internet. Code inside a sandbox can reach the internet; the runner blocks its traffic to private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16), so your LAN is not reachable from a sandbox. The inner Docker data (sandbox image, sandbox containers) lives in the Docker data path. It must be a pool or disk path such as /mnt/cache/..., not /mnt/user/..., because the inner Docker cannot use the user share file system. Image tag :stable follows the latest stable release of the n8n sandbox service. Update this container together with n8n-sandbox-api. Unofficial template, maintained by benjaminmue. The images are published by n8n (n8n-io/n8n-sandbox-service).

Readme

View on GitHub

n8n Sandbox Service

Isolated, on-demand execution environments behind a REST API. Each sandbox is a container (Docker/Sysbox runner) or a Firecracker microVM, with a small HTTP daemon inside that runs commands and handles files. Runners register with a central API, which places sandboxes and proxies requests to them.

Get started

I want to… Read
Run it on a Linux host with Sysbox docs/quickstart-linux.md
Run the Firecracker runner on a KVM host docs/quickstart-firecracker-linux.md
Develop on macOS docs/quickstart-macos.md
Deploy to Kubernetes docs/quickstart-k8s.md
Call the API docs/API.md · TypeScript SDK
Build and test docs/development.md

The full index, including architecture, security model, configuration, operations and release process, is in docs/README.md.

License

Source under the Sustainable Use License. Files and directories with .ee in the name are under the n8n Enterprise License.

Categories

AITools > Utilities

Related apps

Explore more like this

Explore all
AIUtilities apps

Links

Projectgithub.comSupportgithub.comRegistrygithub.comTemplateraw.githubusercontent.com

Details

Repository
ghcr.io/n8n-io/n8n-sandbox-service-runner-dind:stable
Registry
https://github.com/n8n-io/n8n-sandbox-service/pkgs/container/n8n-sandbox-service-runner-dind
Last Updated2026-10-18
First Seen2026-10-18

Runtime arguments

Network
n8n-sandbox
Shell
sh
Privileged
true
Extra Params
--network-alias=n8n-sandbox-runner-1 --restart=unless-stopped

Template configuration

TLS certificatesPathro

The runner/ subfolder of the TLS path of n8n-sandbox-api. Created there on the first start of n8n-sandbox-api.

Target
/tls/runner
Default
/mnt/user/appdata/n8n-sandbox/tls/runner
Value
/mnt/user/appdata/n8n-sandbox/tls/runner
Docker dataPathrw

Storage of the inner Docker engine. Must be a pool or disk path (/mnt/cache/..., /mnt/POOLNAME/...), NOT /mnt/user/...: the inner Docker fails on the user share file system.

Target
/var/lib/docker
Default
/mnt/cache/appdata/n8n-sandbox/docker
Value
/mnt/cache/appdata/n8n-sandbox/docker
Runner registration tokenVariable

Must be identical to Runner registration token in n8n-sandbox-api.

Target
SANDBOX_RUNNER_REGISTRATION_TOKEN
Runner keyVariable

Must be identical to Runner key in n8n-sandbox-api.

Target
SANDBOX_RUNNER_API_KEYS
Sandbox imageVariable

Image of the per-sandbox containers, pulled by the inner Docker on first use.

Target
SANDBOX_RUNNER_DOCKER_SANDBOX_IMAGE
Default
ghcr.io/n8n-io/n8n-sandbox-service-sandbox:stable
Value
ghcr.io/n8n-io/n8n-sandbox-service-sandbox:stable
Runner IDVariable

Do not change.

Target
SANDBOX_RUNNER_ID
Default
runner-1
Value
runner-1
API gRPC addressVariable

Registration endpoint of n8n-sandbox-api on the n8n-sandbox network. Do not change.

Target
SANDBOX_RUNNER_API_GRPC_ADDR
Default
n8n-sandbox-api:9090
Value
n8n-sandbox-api:9090
API server nameVariable

Name in the API certificate. Do not change.

Target
SANDBOX_RUNNER_REGISTRATION_GRPC_SERVER_NAME
Default
n8n-sandbox-api
Value
n8n-sandbox-api
HTTP base URLVariable

Address under which n8n-sandbox-api reaches this runner. Do not change.

Target
SANDBOX_RUNNER_HTTP_BASE_URL
Default
https://n8n-sandbox-runner-1:8080
Value
https://n8n-sandbox-runner-1:8080
Control listen addressVariable

Do not change.

Target
SANDBOX_RUNNER_CONTROL_GRPC_LISTEN_ADDR
Default
:9091
Value
:9091
Control advertise addressVariable

Do not change.

Target
SANDBOX_RUNNER_CONTROL_GRPC_ADVERTISE_ADDR
Default
n8n-sandbox-runner-1:9091
Value
n8n-sandbox-runner-1:9091
Registration CAVariable

Do not change.

Target
SANDBOX_RUNNER_REGISTRATION_GRPC_CA_FILE
Default
/tls/runner/ca.crt
Value
/tls/runner/ca.crt
Registration client certificateVariable

Do not change.

Target
SANDBOX_RUNNER_REGISTRATION_GRPC_CERT_FILE
Default
/tls/runner/grpc-client.crt
Value
/tls/runner/grpc-client.crt
Registration client keyVariable

Do not change.

Target
SANDBOX_RUNNER_REGISTRATION_GRPC_KEY_FILE
Default
/tls/runner/grpc-client.key
Value
/tls/runner/grpc-client.key
Control server certificateVariable

Do not change.

Target
SANDBOX_RUNNER_CONTROL_GRPC_TLS_CERT_FILE
Default
/tls/runner/control-grpc-server.crt
Value
/tls/runner/control-grpc-server.crt
Control server keyVariable

Do not change.

Target
SANDBOX_RUNNER_CONTROL_GRPC_TLS_KEY_FILE
Default
/tls/runner/control-grpc-server.key
Value
/tls/runner/control-grpc-server.key
Control client CAVariable

Do not change.

Target
SANDBOX_RUNNER_CONTROL_GRPC_TLS_CLIENT_CA_FILE
Default
/tls/runner/ca.crt
Value
/tls/runner/ca.crt