Skip to main content

Generating Agent Install Commands

Use the Agent install command to onboard devices to a project securely.

Generate a command:

  1. Open Projects > select your project.
  2. Click Install Agent.
  3. Choose the target OS/architecture (Linux x86_64/ARM, etc.).
  4. Optionally toggle advanced options: pinned version, custom labels, device name, auto-approve (if allowed), and proxy settings.
  5. Copy the generated shell command and run it on the device as root.

What the command does

  • Downloads the Daployi Edge Agent.
  • Registers the device using the Project’s Device Registration Token.
  • Establishes a secure connection to your Daployi server.

Switches and options (explained)

  • Device name

    • You can set a static name with --name. For dynamic naming, shell command substitution is supported (similar to Portainer).
    • Examples: use hostname, or a MAC address to ensure uniqueness.
      • Hostname: --name "$(hostname)"
      • Primary MAC (Linux): --name "$(cat /sys/class/net/eth0/address)"
    • Notes:
      • The $(...) expansion is performed by your shell before running the installer. Test commands first.
      • Quote the value to preserve colons or spaces.

  • Enable Terminal

    • Purpose: Enables in-browser terminal sessions to the device after enrollment.
    • Effect: The agent is configured to accept terminal/exec sessions from authorized users in your Daployi project.
    • Security: Terminal access is audited by Events; restrict via roles/permissions if needed.

  • Use Privileged Mode

    • Purpose: Runs the agent container with the Docker privileged flag, granting broad host access (all capabilities, device access, and many kernel interfaces).
    • When it may be needed: Certain advanced operations (low-level networking, device management, or managing other runtimes) may require privileges on some distros.
    • Risks: Significantly expands the blast radius if the agent or host is compromised. The container can affect the whole host.
    • Safer alternatives (recommended):
      • Use non-privileged mode with targeted capabilities (e.g., --cap-add NET_ADMIN) when supported.
      • Bind only required sockets/paths (e.g., /var/run/docker.sock) instead of full privileges.
    • Guidance: Prefer non-privileged by default; enable privileged only if a specific feature requires it and your security review approves it.

Note on flag names: The UI generates the exact, version-appropriate flags (for example --terminal vs --enable-terminal). Use the command exactly as generated for your version of Daployi.

Examples

  • Standard installation:
docker run -d \
  --name daployi-agent \
  --pid=host --uts=host --ipc=host --net=host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/host:rw,rshared \
  -e CONTROL_SERVER_URL=wss://[YOUR_DOMAIN]/ws/control \
  -e CONTROL_HTTP_BASE=https://[YOUR_DOMAIN] \
  -e AGENT_ID=$(hostname) \
  -e HOST_FS_MOUNT=/host \
  -e DEVICE_NAME="My Device" \
  -e PROJECT_TOKEN="[PROJECT TOKEN]" \
  daployi/daployi-agent:1.0.2
  • Enable Terminal and non-privileged (recommended default):
docker run -d \
  --name daployi-agent \
  --cap-add SYS_ADMIN \
  --cap-add SYS_PTRACE \
  --pid=host --uts=host --ipc=host --net=host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/host:rw,rshared \
  -e CONTROL_SERVER_URL=wss://[YOUR_DOMAIN]/ws/control \
  -e CONTROL_HTTP_BASE=https://[YOUR_DOMAIN] \
  -e AGENT_ID=$(hostname) \
  -e HOST_FS_MOUNT=/host \
  -e DEVICE_NAME="My Device" \
  -e PROJECT_TOKEN="[PROJECT TOKEN]" \
  daployi/daployi-agent:1.0.2
  • Privileged mode with MAC-based device name (only if required):
docker run -d \
  --name daployi-agent \
  --privileged \
  --pid=host --uts=host --ipc=host --net=host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /:/host:rw,rshared \
  -e CONTROL_SERVER_URL=wss://[YOUR_DOMAIN]/ws/control \
  -e CONTROL_HTTP_BASE=https://[YOUR_DOMAIN] \
  -e AGENT_ID=$(hostname) \
  -e HOST_FS_MOUNT=/host \
  -e DEVICE_NAME="My Device" \
  -e PROJECT_TOKEN="[PROJECT TOKEN]" \
  daployi/daployi-agent:1.0.2

Security notes

  • Treat the install command like a secret. It contains a scoped token.
  • Rotate the Project Device Registration Token if it is exposed.
  • Minimize privileges: Avoid --privileged unless absolutely necessary; prefer targeted capabilities and restrictive mounts.