Remote Environments

Manage other Docker hosts from one Arcane Manager. Each remote host runs a small Arcane Agent that connects out to the Manager and relays requests to its local Docker engine. The agent opens no ports, so the host can sit behind NAT or a firewall.

Requirements

• The Arcane Manager is running and the agent host can reach its URL.
• Docker or Podman is on the agent host, and the agent can mount its socket at /var/run/docker.sock. For Podman, mount the Podman socket there as in Run Arcane on Podman.
• You create the environment in Arcane before starting the agent.
• You use the agent image ghcr.io/getarcaneapp/agent. Arcane 3.0 no longer publishes the old ghcr.io/getarcaneapp/arcane-headless alias.

Add an environment

1. Open Environments → Add Environment, enter a name, and click Generate Agent Configuration. Arcane derives the address from the name and issues an API key.
2. Copy the API key now. It isn’t shown again.
3. Run the generated docker run command or Compose file on the remote host.

For client-certificate security, turn on Enable manager mTLS before generating. See Edge Agent mTLS. The generated Compose file:

services:
  arcane-edge-agent:
    image: ghcr.io/getarcaneapp/agent:latest
    container_name: arcane-edge-agent
    restart: unless-stopped
    environment:
      - ARCANE_EDGE_AGENT=true
      - ARCANE_EDGE_TRANSPORT=auto
      - ARCANE_AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      - ARCANE_MANAGER_API_URL=https://your-manager.example.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data

volumes:
  arcane-data:

The agent won’t start without ARCANE_MANAGER_API_URL and ARCANE_AGENT_TOKEN. It listens on no port, so HTTP health checks like the old curl http://localhost:3553/api/health no longer work. Watch the environment’s status in Arcane instead.

Choose a transport

ARCANE_EDGE_TRANSPORT sets how the agent stays in touch with the Manager. Behind Traefik, see Reverse Proxy Setup → Traefik for the tunnel routes.

Value	Behaviour
auto	Continuous tunnel, gRPC where possible with WebSocket fallback. The default; generated snippets use it.
poll	Checks in periodically. The first action on an idle environment can take a moment while the connection wakes.
websocket / grpc	Continuous WebSocket or gRPC tunnel. grpc has no WebSocket fallback.

Status meanings

Status	Meaning
Online	A tunnel is active right now.
Standby	In poll mode, the agent is checking in and waiting for demand. This is healthy.
Pending	No agent has enrolled yet. Regenerate the API key to get the install command, then run it.
Offline / Error	The Manager can’t currently use this environment.

Run the agent as a standalone binary

Download the latest arcane-agent release for your platform onto the host. Create a .env file next to it, then run ./arcane-agent:

ARCANE_EDGE_AGENT=true
ARCANE_EDGE_TRANSPORT=auto
ARCANE_AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
ARCANE_MANAGER_API_URL=http://10.1.1.4:3552
ARCANE_ENVIRONMENT=production

Re-enroll an agent

Do this when a key is lost or leaked, or when an environment converted from a direct agent shows Pending after upgrading to 3.0. The environment keeps its ID, so webhooks, Git syncs, settings, jobs, and color stay attached.

1. Open the environment under Environments. On the Connection & Agent tab, click Regenerate API Key and confirm. The old key stops working immediately.
2. Copy the new key and run the shown install command on the agent host, replacing the old agent container.

Work across environments

Arcane shows every environment you can read. Lists, the dashboard, network topology, Swarm, Security, Git Syncs, and Podman pages combine them all, with an Environment column and filter. Row actions run in that row’s environment; create forms have an Environment field. Lists and the dashboard update live when any environment changes. Detail pages carry the environment in the URL, like /containers/<id>?env=2, so shared links open the right host.

An admin can set Environment limit from the settings button on the Environments page to cap how many environments any list includes, from 2 to 256, default 64; extras are reported as not included. Under Account → Preferences → Environments, each user can color environments and show either the name or a color dot in lists.

Edit an environment

Click an environment under Environments to open it. Click the header name to rename it; the local environment can’t be renamed. Arcane names the local environment after its host on first creation, and renames one still called Local Docker from an older version. The header also has the address with a copy button, Test Connection, Sync, and Easy Join when the environment can join a Swarm. An online remote environment can join with Easy Join; its agent then serves the Swarm node without a new token. See Swarm Cluster.

Tab	What it contains
Connection & Agent	Remote environments only. Tunnel and heartbeat status, the agent’s mTLS certificate and downloads, and Regenerate API Key.
Features	Turn Swarm and vulnerability management on or off for this environment.
Engine	Docker or Podman engine details. Needs system:read.
History	Job run history for this environment. Needs jobs:manage.

Everything else lives under Settings. Notifications are under System → Notifications.

A disabled environment shows only Connection & Agent and Features. Offline environments keep their tabs, but details can’t load until they reconnect.

Environment settings

Per-environment settings live under Settings: Storage & Limits, Docker, Security, Timeouts, Activity, Builds, and Automations.

Pick an environment under Applying settings for at the top of each page, or choose all environments to edit them together. Offline environments are left out.

When environments disagree on a value, the field shows Mixed. Click it to see each value and which environments have it, then Use for all to apply one everywhere.

Update all environments

To upgrade the Manager and agents together, open Environments, click Update All, and confirm in the Update all environments dialog.

Note

This updates Arcane itself and needs the system:upgrade permission. To update containers and projects, use Updates.

Agents update first, up to 4 at a time by default. Change that with Parallel agent upgrades (1–16) from the settings button on the Environments page. Then the Manager updates, which restarts only if its image changed. Offline environments are skipped. Each row shows old and new versions and a status.

Status	Meaning
Pending / Updating	Waiting in the queue, or upgrade in progress.
Updated / Update triggered	The new version was applied, or handed off to the agent to finish.
Up to Date / Offline — skipped	Nothing to do, or the environment was unreachable.
Failed	The upgrade didn’t complete. The error is shown inline.