n8n-sandbox-api
Docker app from benjaminmue's Repository
Overview
Code sandbox for the n8n Assistant and n8n Agents, self-hosted on Unraid. Only useful together with an existing n8n container: this is not n8n itself, it is the isolated environment n8n uses to run AI-generated code and work with files. n8n stays where it is; you only point it at this service.
The sandbox is two containers and both are needed: n8n-sandbox-api (this one, the control plane n8n talks to) and n8n-sandbox-runner (privileged Docker-in-Docker that starts one throwaway container per sandbox). They talk to each other over mutual TLS. This container creates the certificates on its first start, so there is nothing to generate by hand.
Setup:
- Settings - Docker: set "Preserve user defined networks" to Yes, otherwise Unraid deletes the network below on every Docker restart.
- Create the network once in the Unraid terminal: docker network create n8n-sandbox
- Install this container. Fill in the three keys with long random values, for example from: openssl rand -hex 32
- Install n8n-sandbox-runner with the same registration token and runner key.
- In n8n open Settings - n8n Assistant (or Agents) - Add a code sandbox, choose n8n Sandbox and enter the service URL and the API key. Service URL: http://n8n-sandbox-api:8080 if n8n is attached to the n8n-sandbox network, otherwise http://Unraid-IP:3200 (the host port below).
Check: http://Unraid-IP:3200/healthz answers {"status":"ok"}, and the log of this container shows "runner registered". On its first start the runner first brings up its own Docker engine and only then registers. Until it has, the connection test in n8n fails with "no sandbox runners are registered or available": wait a moment and test again.
Image tag :stable follows the latest stable release of the n8n sandbox service. API and runner are released together and only supported in the same version, so update both containers at the same time.
Security: LAN only. Never forward port 3200 to the internet. The runner is privileged and equivalent to root on the host.
Unofficial template, maintained by benjaminmue. The images are published by n8n (n8n-io/n8n-sandbox-service).
Readme
View on GitHubn8n 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
Related apps
Explore more like this
Explore allDetails
ghcr.io/n8n-io/n8n-sandbox-service-api:stableRuntime arguments
- Network
n8n-sandbox- Shell
sh- Privileged
- false
- Extra Params
--network-alias=n8n-sandbox-api --user=0:0 --entrypoint=/bin/sh
Template configuration
Host port for the sandbox API. Only needed if n8n is NOT on the n8n-sandbox network; n8n then uses http://UNRAID-IP:3200. LAN only, never expose to the internet.
- Target
- 8080
- Default
- 3200
- Value
- 3200
Mutual TLS material, created on the first start: root CA, API certificates under api/, runner certificates under runner/. The runner mounts the runner/ subfolder of this path. Delete the folder and restart both containers to issue new certificates.
- Target
- /tls
- Default
- /mnt/user/appdata/n8n-sandbox/tls
- Value
- /mnt/user/appdata/n8n-sandbox/tls
SQLite database with sandboxes, runners and tenants.
- Target
- /data
- Default
- /mnt/user/appdata/n8n-sandbox/api
- Value
- /mnt/user/appdata/n8n-sandbox/api
The key n8n uses to talk to this service. Enter the same value in n8n under Add a code sandbox - API key. Generate with: openssl rand -hex 32
- Target
- SANDBOX_API_KEYS
Shared secret the runner presents when it registers. Must be identical to Runner registration token in n8n-sandbox-runner.
- Target
- SANDBOX_API_RUNNER_REGISTRATION_TOKEN
Key this service uses to call the runner. Must be identical to Runner key in n8n-sandbox-runner.
- Target
- SANDBOX_API_RUNNER_API_KEY
Name in the runner certificate. Matches the network alias of n8n-sandbox-runner. Do not change.
- Target
- SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_SERVER_NAME
- Default
- n8n-sandbox-runner-1
- Value
- n8n-sandbox-runner-1
Location of the SQLite database inside the container. Do not change.
- Target
- SANDBOX_API_DATA_DIR
- Default
- /data
- Value
- /data
Do not change.
- Target
- SANDBOX_API_GRPC_TLS_CERT_FILE
- Default
- /tls/api/grpc-server.crt
- Value
- /tls/api/grpc-server.crt
Do not change.
- Target
- SANDBOX_API_GRPC_TLS_KEY_FILE
- Default
- /tls/api/grpc-server.key
- Value
- /tls/api/grpc-server.key
Do not change.
- Target
- SANDBOX_API_GRPC_TLS_CLIENT_CA_FILE
- Default
- /tls/api/ca.crt
- Value
- /tls/api/ca.crt
Do not change.
- Target
- SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CA_FILE
- Default
- /tls/api/ca.crt
- Value
- /tls/api/ca.crt
Do not change.
- Target
- SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CERT_FILE
- Default
- /tls/api/control-grpc-api-client.crt
- Value
- /tls/api/control-grpc-api-client.crt
Do not change.
- Target
- SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_KEY_FILE
- Default
- /tls/api/control-grpc-api-client.key
- Value
- /tls/api/control-grpc-api-client.key