Remote Environments

A remote environment is another Docker host that you manage from the same Arcane Manager. Each remote host runs a small Arcane Agent that talks to its local Docker and relays requests from the Manager.

The agent connects in one of two modes:

Requirements

• The Arcane Manager is running.
• Docker is installed on the agent host and the agent can mount /var/run/docker.sock.
• The environment is created in Arcane before you start the agent.
• Direct: the Manager can reach the agent on port 3553.
• Edge: the agent can reach the Manager’s URL.

The agent image is ghcr.io/getarcaneapp/agent. ghcr.io/getarcaneapp/arcane-headless is a supported alias of the same image for existing installations.

Add a Direct environment

1. Open Environments → Add Environment.
2. Enter a name.
3. Enter the Agent API URL, for example http://my-agent:3553 or https://10.1.1.5:3553.
4. Create the environment.
5. Copy the generated docker run or Docker Compose snippet and run it on the remote host.

The generated Compose file looks like this:

services:
  arcane-agent:
    image: ghcr.io/getarcaneapp/agent:latest
    container_name: arcane-agent
    ports:
      - '3553:3553'
    environment:
      - AGENT_MODE=true
      - AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      - MANAGER_API_URL=http://10.1.1.4:3552
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data
    restart: unless-stopped

volumes:
  arcane-data:

Start it with docker compose up -d.

Add an Edge environment

1. Open Environments → Add Environment.
2. Switch to the Edge tab.
3. Enter a name and click Generate Agent Configuration.
4. Copy the generated snippet and run it on the remote host.

The generated Compose file looks like this. No ports are published because the agent connects out to the Manager.

services:
  arcane-edge-agent:
    image: ghcr.io/getarcaneapp/agent:latest
    container_name: arcane-edge-agent
    environment:
      - EDGE_AGENT=true
      - EDGE_TRANSPORT=poll
      - AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      - MANAGER_API_URL=https://your-manager.example.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data
    restart: unless-stopped

volumes:
  arcane-data:

To secure the Edge connection with client certificates, see Edge Agent mTLS.

Choose a transport

EDGE_TRANSPORT sets how an Edge agent keeps in touch with the Manager. It has no effect on Direct agents.

Behind Traefik, see Reverse Proxy Setup → Traefik for the tunnel routes.

Edge status meanings

In poll mode, an Edge environment shows one of these statuses:

Run the agent as a standalone binary

You can run the agent as a binary instead of a container.

1. Download the latest release for your platform.
2. Place the binary on the target host.
3. Create a .env file next to it.

Direct agent .env:

AGENT_MODE=true
AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
MANAGER_API_URL=http://10.1.1.4:3552
ENVIRONMENT=production
PORT=3553
LISTEN=127.0.0.1

Edge agent .env:

EDGE_AGENT=true
EDGE_TRANSPORT=poll
AGENT_TOKEN=arc_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
MANAGER_API_URL=http://10.1.1.4:3552
ENVIRONMENT=production

LISTEN sets the interface the agent binds to. Leave it empty to bind all interfaces.

Start the agent:

Or pass everything inline:

Edit an environment

Select an environment under Environments. Click its name or API URL in the header to edit them; both are read-only for the local environment. The header also has Test Connection, a button to copy the API URL, and Regenerate API Key for non-Edge environments.

The environment page has these tabs:

An offline or disabled environment shows only Git Syncs, and stays open so you can fix the connection from the header.

Update all environments

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

Agents update first, then the Manager. The Manager restarts only if its image changed, and offline environments are skipped. Each row shows the old and new versions and a status:

Join an environment to a Swarm

An online remote environment can join a Swarm cluster with Easy Join, and the same agent then serves its Swarm node without a new token. See Swarm Cluster for the steps.