Install an Agent

Use this guide when

Use this page when you need to:

• install EnderDash on a new runtime
• reinstall after rotating an agent key
• move a server record to a different runtime

Before you begin

You need:

• an active subscription on the organization
• a server record in Servers
• owner or admin access, because Downloads and agent-key management are admin-only

Pick the correct download

Open Downloads, select the server record, and choose the build that matches the runtime:

Do not reuse a Bukkit build on a proxy or a standalone host. The runtime must match the artifact.

Container platform support

EnderDash supports common operational workflows for Docker-compatible hosts and Kubernetes clusters. It is not a replacement for every native platform tool.

For Kubernetes custom resources, use the CRD browser or enter the API group, version, and plural resource name in the dashboard. The agent uses those values to list and inspect matching objects, but your cluster RBAC must already grant get and list for that API group and resource plural.

For a detailed feature and RBAC reference, see Container Platforms.

Install the runtime package

Plugin and proxy runtimes

1. Drop the downloaded jar into the runtime's plugins/ directory.
2. Restart the runtime so it loads the plugin and exposes the enderdash console command. Without this restart the command does not exist yet.
3. Run enderdash install <agentKey> in the console. The agent connects immediately, no second restart needed.

agentKey: "<agentKey>"

java -Denderdash.agentKey='<agentKey>' -jar server.jar

export ENDERDASH_AGENT_KEY='<agentKey>'

Standalone runtimes

1. Place the standalone artifact in the directory where it will run.
2. Save the agent key in ~/.enderdash/config.yml.
3. Start the standalone runtime.

agentKey: "<agentKey>"

java -Denderdash.agentKey='<agentKey>' -jar EnderDash-Standalone.jar

export ENDERDASH_AGENT_KEY='<agentKey>'
java -jar EnderDash-Standalone.jar

Docker hosts

Run the standalone agent image and mount the Docker socket only on hosts where EnderDash should inspect or manage local containers:

docker run -d --name enderdash-agent \
  --restart unless-stopped \
  -e ENDERDASH_AGENT_KEY='<agentKey>' \
  -v enderdash-agent-data:/enderdash/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/enderdash-com/enderdash-agent:latest

The socket mount gives the agent broad control over the local Docker daemon. Use a dedicated host or a tightly controlled server record when you enable container management.

To run the same setup with Docker Compose:

curl -fsSLO https://raw.githubusercontent.com/enderdash-com/deploy/main/agent/compose.yaml
cat > .env <<'EOF'
ENDERDASH_AGENT_KEY=<agentKey>
EOF
docker compose up -d

Check the container:

docker compose ps

After the agent is connected, the Containers panel can create Minecraft server presets on the same Docker or Podman host. The preset uses itzg/minecraft-server, creates a persistent /data volume, publishes the Minecraft port, installs the EnderDash Modrinth plugin through MODRINTH_PROJECTS, and writes plugins/EnderDash/config.yml with the agent key you provide.

The same preset flow can target Docker Swarm. EnderDash creates a Swarm service with the Minecraft server image, published ports, persistent data volume, and EnderDash labels so the service is visible in Swarm inventory.

Podman hosts

Start the Podman API service first, then run the same agent image against the Podman socket:

systemctl --user enable --now podman.socket

podman run -d --name enderdash-agent \
  --replace \
  --restart unless-stopped \
  --group-add keep-groups \
  -e ENDERDASH_AGENT_KEY='<agentKey>' \
  -v enderdash-agent-data:/enderdash/data \
  -v "${XDG_RUNTIME_DIR}/podman/podman.sock:/run/podman/podman.sock" \
  -e DOCKER_HOST=unix:///run/podman/podman.sock \
  ghcr.io/enderdash-com/enderdash-agent:latest

Rootless Podman exposes only the containers owned by that user. --group-add keep-groups keeps the user's supplementary groups available to the container process so the mounted socket can be opened. Use a rootful socket only when the server record is allowed to manage system containers.

To run the agent as a rootless Podman systemd user service:

mkdir -p ~/.config/containers/systemd
curl -fsSL https://raw.githubusercontent.com/enderdash-com/deploy/main/agent/quadlet/enderdash-agent.container \
  -o ~/.config/containers/systemd/enderdash-agent.container
curl -fsSL https://raw.githubusercontent.com/enderdash-com/deploy/main/agent/quadlet/enderdash-agent-data.volume \
  -o ~/.config/containers/systemd/enderdash-agent-data.volume

cat > ~/.config/containers/systemd/enderdash-agent.env <<'EOF'
ENDERDASH_AGENT_KEY=<agentKey>
EOF
chmod 600 ~/.config/containers/systemd/enderdash-agent.env

systemctl --user enable --now podman.socket
systemctl --user daemon-reload
systemctl --user enable --now enderdash-agent.service

Check the service:

systemctl --user status enderdash-agent.service

Kubernetes clusters

Use the public Kustomize manifests or the public Helm chart. Both install the standalone agent image and read the agent key from the same Secret.

Create the namespace and Secret:

kubectl create namespace enderdash
kubectl -n enderdash create secret generic enderdash-agent \
  --from-literal=agentKey='<agentKey>'

Install the read-only Kustomize manifests when EnderDash should inspect cluster state without running Kubernetes mutations:

kubectl apply -k 'https://github.com/enderdash-com/deploy//agent/kustomize/base?ref=main'

Install operator mode instead when EnderDash should be allowed to run Kubernetes actions such as restarts, scaling, exec, port-forward, debug containers, and YAML apply or delete:

kubectl apply -k 'https://github.com/enderdash-com/deploy//agent/kustomize/operator?ref=main'

The public EnderDash Helm repository provides the same two RBAC modes:

helm repo add enderdash https://charts.enderdash.com
helm repo update

helm install enderdash-agent enderdash/enderdash-agent \
  --namespace enderdash \
  --set rbac.mode=readonly

Use rbac.mode=operator only for clusters where EnderDash should run Kubernetes mutations such as rollout restarts, StatefulSet scaling, CronJob suspension, pod debug containers, pod exec, port-forward sessions, and YAML apply or delete actions.

Operator mode also enables Minecraft server presets for Kubernetes. A preset creates a Secret for the EnderDash plugin config, a PVC for /data, a Service for the Minecraft port, and a StatefulSet running itzg/minecraft-server with the EnderDash Modrinth plugin enabled.

The chart exposes production knobs for image pull secrets, pod labels and annotations, pod and container security contexts, resource requests and limits, persistence, node selectors, tolerations, and affinity. Enable persistence.enabled=true when the standalone agent needs state to survive pod replacement instead of using the default emptyDir volume.

The Kustomize source lives in the EnderDash deploy repository. The Helm chart source lives in the EnderDash Helm charts repository.

Reinstall after a key rotation

If Downloads shows a fresh agent key, the previous key is no longer valid for that server record.

• On runtimes with the command surface, run enderdash install <agentKey> again.
• On standalone or manual setups, replace the old agentKey value in the config file, JVM property, or ENDERDASH_AGENT_KEY environment variable and restart.

Manual fallback

If the runtime does not expose the enderdash console command, use the config file, a JVM property, or an environment variable. These options are supported by Bukkit, Velocity, BungeeCord, Hytale, and standalone runtimes.

agentKey: "<agentKey>"
signalingUrl: "wss://signaling.enderdash.com/ws"

Use signalingUrl only if you need to override the default signaling host.

java -Denderdash.agentKey='<agentKey>' -jar server.jar

Set the JVM property before the jar argument in your startup command.

export ENDERDASH_AGENT_KEY='<agentKey>'

Set the environment variable in the shell, service, or host panel environment that starts the runtime.

Verify the result

The install is complete when:

• the server shows Online
• the server page opens without setup prompts
• live panels begin loading data

If the runtime starts but EnderDash still shows the server as offline, continue with Recover an Offline Server.

Related pages

• Agent Commands
• Network Requirements
• Connection Model