If you run Docker on more than one machine, you probably know the routine: SSH into a box, cd into a folder, docker compose ps, tail some logs, repeat on the next server. It works, but it does not scale well once you have a handful of hosts and a few dozen stacks.
Arcane is an open-source, self-hosted web UI for Docker and Docker Compose that tries to fix that without making you learn a new orchestration model. It sits on top of the Docker you already have and gives you a dashboard, a Compose editor, logs, a terminal, and multi-host management from one place.
This article covers what Arcane is, how to get it running, and the details that matter when you move past "it works on my laptop."
What Arcane is (and is not)
Arcane is:
- A web UI for Docker and Compose. Containers, images, volumes, networks, and Compose "projects" (stacks) are all first-class.
- Self-hosted, single container. You run it next to your workloads and talk to Docker through the socket (or a socket proxy).
- Open source under BSD-3-Clause. No paid tiers, no feature gating.
- Built with Go and SvelteKit. The backend is Go, the frontend is SvelteKit with TypeScript.
Arcane is not:
- An orchestrator. It does not replace Kubernetes or Swarm scheduling. It manages Docker and Compose the way you already use them.
- A new config format. Your stacks stay as normal
compose.yamlfiles on disk. If you stop using Arcane tomorrow,docker compose up -dstill works.
That last point is the main reason a lot of developers are trying it. There is no lock-in. Arcane reads and writes standard Compose files.
Feature overview
Here is what you get out of the box:
| Area | What you get |
|---|---|
| Containers | Start, stop, restart, inspect, real-time logs, web terminal, process list |
| Compose projects | Create and edit stacks in the browser, deploy, pull, redeploy |
| Images | Browse, pull, prune, browse registry repos and tags, build workspace |
| Networks | Management plus an interactive network topology view |
| Multi-host | Manage remote Docker hosts through agents (direct or edge mode) |
| GitOps | Point Arcane at a Git repo and sync stacks from it |
| Updates | Tag-based auto-updates with an optional cool-down delay |
| Security | Trivy vulnerability scanning, image patching with Copacetic |
| Auth | Local users, OIDC/SSO, passkeys, MFA, role mappings |
| Ops | Scheduled volume and S3 backups, OpenTelemetry export |
| Automation | REST API and a Go-based CLI (arcane-cli) |
| Runtimes | Docker, plus Podman (rootful, rootless, and quadlets) |
Quick start
You need Docker and Docker Compose on the host.
1. Generate an encryption key
Arcane requires a 32-byte ENCRYPTION_KEY. Either of these works:
openssl rand -hex 32 docker run --rm ghcr.io/getarcaneapp/manager:v2 /app/arcane generate secret 2. Create compose.yaml
services: arcane: image: ghcr.io/getarcaneapp/manager:v2 container_name: arcane restart: unless-stopped ports: - "3552:3552" environment: - APP_URL=http://localhost:3552 - ENCRYPTION_KEY=replace-with-your-generated-key - PROJECTS_DIRECTORY=/opt/stacks - TZ=UTC volumes: - /var/run/docker.sock:/var/run/docker.sock - arcane-data:/app/data - /opt/stacks:/opt/stacks volumes: arcane-data: 3. Start it
docker compose up -d Open http://<your-host>:3552 and log in with the default credentials:
- Username:
arcane - Password:
arcane-admin
You will be forced to change the password on first login.
Things developers should know
The quick start gets you running. These are the details that save you time later.
1. Use the current image name and pin v2
The image moved from ghcr.io/getarcaneapp/arcane to ghcr.io/getarcaneapp/manager. Many older blog posts and templates still use the old name. Official mirrors also exist on Docker Hub (getarcaneapp/manager) and Quay (quay.io/getarcaneapp/manager).
Pin the v2 tag for anything you care about. Avoid latest and any beta tags in production.
2. Keep host and container paths identical for stacks
Notice the stacks volume above: /opt/stacks:/opt/stacks. Compose files often use relative paths for bind mounts (./data:/data). When Arcane runs docker compose from inside its container, those paths are resolved against the Docker host, not the Arcane container.
Arcane can translate mismatched paths now, but mounting the same path on both sides is still the recommended setup and avoids surprises. PROJECTS_DIRECTORY also accepts a <containerPath>:<hostPath> form if you need them to differ.
3. Mounting the Docker socket is root-equivalent
Anything with access to /var/run/docker.sock can effectively control the host. That is true for Arcane and for every other Docker UI.
For hardened setups, put a socket proxy in front of Docker and point Arcane at it:
environment: - DOCKER_HOST=tcp://docker-socket-proxy:2375 Then remove the socket mount from the Arcane service. Two common proxies are wollomatic/socket-proxy (deny-by-default) and Tecnativa/docker-socket-proxy. Take the exact allow-list from Arcane's socket proxy docs rather than guessing.
One gotcha: if you use wollomatic/socket-proxy with -allowfrom, include arcane-upgrader as well as arcane. Self-upgrades run through a helper with that alias and will fail without it.
4. Every secret supports _FILE
Any sensitive variable can be read from a file by adding _FILE. This plays well with Docker secrets:
environment: - ENCRYPTION_KEY_FILE=/run/secrets/arcane_encryption_key secrets: - arcane_encryption_key Also note that JWT_SECRET from older guides is no longer used in 2.x. Arcane generates and stores its own session signing key. If you still set JWT_SECRET, you just get a warning at startup, so remove it.
5. Behind a reverse proxy, set TRUSTED_PROXIES and APP_URL
If Arcane sits behind Nginx, Traefik, Caddy, or a Cloudflare Tunnel:
- Set
APP_URLto the public URL (for examplehttps://arcane.example.com, no port). - Set
TRUSTED_PROXIESto the CIDR of your proxy. Without it, client IPs in logs and rate limiting will be wrong. - Make sure WebSockets are passed through. Logs and the terminal depend on them. In Nginx that means
proxy_http_version 1.1plus theUpgradeandConnection "upgrade"headers.
Minimal Nginx location block:
location / { proxy_pass http://127.0.0.1:3552; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } Arcane can also serve HTTPS itself with TLS_ENABLED, TLS_CERT_FILE, and TLS_KEY_FILE if you prefer not to run a proxy.
6. Managing multiple hosts: direct vs edge agents
To manage other servers, run the Arcane agent (ghcr.io/getarcaneapp/agent) on each one. There are two modes:
- Direct mode. The manager connects to the agent on TCP port 3553. Simple, but the agent must be reachable from the manager.
- Edge mode. The agent dials out to the manager over mTLS. No inbound port is needed on the remote host, which makes it a good fit for machines behind NAT or a home router.
You do not need to write the agent config by hand. In the UI, go to Environments > Add Environment and Arcane generates a token and a ready-to-paste Compose snippet.
Edge agents support several transports through EDGE_TRANSPORT:
-
auto(default): gRPC tunnel with WebSocket fallback -
grpcorwebsocket: force one tunnel type -
poll: periodic check-in with no persistent tunnel, useful behind Cloudflare Tunnel or strict proxies
An agent in poll mode shows as Standby when idle. That is normal and means it is healthy.
If you run Traefik in front of the manager with edge agents on auto or grpc, disable the entrypoint read timeout, otherwise tunnels drop after about 60 seconds.
7. GitOps without a CI pipeline
You can point Arcane at a Git repository that contains your Compose files and it will keep the stacks in sync. For small teams and home labs this is often enough to get a "push to deploy" flow without setting up webhooks or a CI runner. Use SSH_KNOWN_HOSTS to pin host keys when cloning over SSH.
8. Auto-updates with a safety delay
Arcane can update containers when a new image is published for the tag you track. To reduce the risk of pulling a compromised or broken image the minute it lands, you can set an update delay in hours.
Per project, in your Compose file:
x-arcane: updater: delay: 72 Or per container, with a label:
labels: - com.getarcaneapp.arcane.updater.delay=72 A value of 0 on a service opts it out of the delay.
9. Automate it: API and CLI
Arcane exposes a REST API, and there is a Go CLI for scripting:
go install github.com/getarcaneapp/arcane/cli/v2@latest For automation, ADMIN_STATIC_API_KEY lets you provision a fixed API key through the environment instead of creating one in the UI.
10. Use SSO if you share it with a team
OIDC is configured under Settings > Authentication or through environment variables (OIDC_ENABLED, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_SCOPES). The redirect URI is:
https://<your-arcane-url>/auth/oidc/callback You can map IdP group claims to Arcane roles with OIDC_ROLE_MAPPINGS, including per-environment roles. If you ever lock yourself out, a local backup login is available at /login/backup.
A small but common mistake: when you use the list form of environment: in Compose, do not wrap OIDC values in quotes. The quotes become part of the value and discovery fails.
Useful environment variables
| Variable | Purpose | Default |
|---|---|---|
ENCRYPTION_KEY | Required 32-byte key for encrypting stored secrets | none |
APP_URL | Public URL of the UI | http://localhost:3552 |
PROJECTS_DIRECTORY | Where Compose projects live | /app/data/projects |
DOCKER_HOST | Docker endpoint, use tcp:// for a socket proxy | unix:///var/run/docker.sock |
PUID / PGID | User and group the app runs as | 65532 |
TRUSTED_PROXIES | CIDR of reverse proxies | unset |
DATABASE_URL | Database connection | SQLite |
TLS_ENABLED | Serve HTTPS directly | false |
LOG_LEVEL | Log verbosity | info |
TZ | Time zone | system |
If the container cannot talk to the Docker socket because of permissions, either run it as root or add the host's docker group ID with group_add.
How it compares
Arcane overlaps with tools like Portainer, Dockge, and Komodo. A rough way to think about it:
- Portainer is the long-standing, broad option, with some features in paid editions.
- Dockge focuses narrowly on Compose stack editing on a single host.
- Arcane aims for a modern UI with Compose at the center, built-in multi-host agents, GitOps, security scanning, and SSO, all under a permissive open-source license with no paid tier.
The best choice depends on how many hosts you run and how much you want built in. Arcane is easy to try side by side with whatever you use now, since it works on plain Compose files.
Links:
- Repository: https://github.com/getarcaneapp/arcane
If you try it, share your setup in the comments. I am curious how people are running it across multiple hosts.
