AI agents in Docker and Docker Compose

If your AI agent — OpenClaw or Hermes — runs inside a Docker container, the sensor’s kernel-level protection (file access, process execution, network decisions) covers it automatically. Two protection layers, however, need settings inside the container: HTTPS traffic analysis (the container must trust the sensor’s certificate authority) and agent-action events (the agent plugin must reach the sensor’s AppHook socket). This page shows how to get those layers wired — whether you are starting fresh or already have an agent running.

There are two paths:

• Starting fresh? Let the sensor create a fully managed agent container for you — one command, protected from the first second.
• Already running an agent in Docker or Docker Compose? Protect the existing container in place with protect-container — a one-time recreate that keeps your data and configuration.

Everything on this page runs on the host where the sensor is installed, as root (or with sudo). Install the sensor first: Install the sensor.

What protection adds to a container#

A protected container differs from an unprotected one in three ways:

1. Imunify labels (imunify.ai.managed=1) so the sensor recognizes and tracks the container across restarts.
2. Certificate trust — the sensor’s CA certificate is mounted read-only into the container and wired into the environment (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, and friends), so HTTPS analysis works without certificate errors.
3. AppHook socket — the sensor’s socket is mounted into the container so the agent plugin can report prompts, tool calls, and responses as events.

Docker containers are immutable: these settings cannot be added to a running container in place. That is why both paths below involve creating (or recreating) the container once.

Path 1: Create a new managed agent container#

If you do not have an agent running yet, this is the fastest way — the sensor creates the container with all protection wired in from the start:

# OpenClaw
sudo imunify-agent-support create-openclaw-container

# Hermes
sudo imunify-agent-support create-hermes-container

The command pulls the agent image, creates a managed container with the labels, certificate trust, and socket mounts already in place, and starts it. Useful options (both runtimes):

When it finishes, the container shows up in the Panel as a protected agent, and every prompt and tool call it makes lands on the Events page.

Path 2: Protect an existing container#

Already running an agent in Docker? One command brings it under protection:

sudo imunify-agent-support protect-container <container-name-or-id>

The command works for both standalone docker run containers and Docker Compose services — it detects which one you have and picks the right strategy. Before changing anything it prints a plan (what will change, expected downtime, how rollback works) and asks for confirmation. Add --dry-run to see the plan without doing anything, or --yes to skip the confirmation prompt in scripts.

Standalone Docker containers#

Supported for OpenClaw and Hermes. For a container started with docker run, protect-container:

1. Backs up the original container configuration.
2. Stops the container and recreates it with the Imunify labels, certificate/AppHook environment, and read-only mounts added. Your volumes, network settings, and environment are preserved.
3. Starts the new container and verifies it is healthy.

Downtime: the container is stopped and recreated, so in-memory work is interrupted — in-flight agent conversations are cut. Persistent state on volumes is untouched.

Rollback: if anything fails, the original container and runtime configuration are restored automatically.

Docker Compose services#

For a Compose-managed container the in-place approach would not survive: the next docker compose up recreates the service from your project files and would silently drop every Imunify setting. So protect-container takes a durable route instead:

1. It writes a docker-compose.override.yml next to your compose file. The override carries all the Imunify settings and is loaded automatically by Compose — your own compose file is never modified.
2. It recreates the service once via docker compose up -d --no-deps.

From then on the protection survives every future docker compose up, image update, and service recreate, because Compose keeps applying the override.

Downtime: the service is recreated by Compose; in-memory work is interrupted.

Rollback: on failure the override file is removed (or the previous one restored) and Compose re-applies your original definition.

Note: Docker Compose protection currently supports OpenClaw only and is considered experimental. A Hermes container managed by Compose is still covered by kernel-level protection; for the in-container layers, run it standalone for now. If something does not work, contact support@imunify.ai.

The installer offers this for you#

When you install the sensor on a host that already runs a Compose-managed OpenClaw container, the installer detects it and asks right there:

Docker Compose openclaw agent detected: openclaw-openclaw-gateway-1 (1d8e46e81605).
  To protect it, Imunify writes a compose override file next to your
  compose file and recreates the service once. ...
  Protect openclaw-openclaw-gateway-1 now (write override + recreate the service)? [y/N]

• Answer y and the installer runs the protect flow immediately — nothing else to do.
• Answer n (or run non-interactively) and the installer prints the exact protect-container command to run later, and records a pending action so the reminder shows up in the install summary and in the Panel. Nothing is ever done to your container without consent, and the install never fails because of this step.

Hosts that need a reboot: on some distributions the installer has to enable LSM BPF in the boot configuration and asks you to reboot before the sensor can start. On those hosts the question is still asked during install — answering y queues your consent, and a one-shot service applies the protection automatically right after the reboot, once the sensor is up. You can check how it went with:

journalctl -u imunifyai-postboot-protect -b

If the automatic run could not protect the container (for example, the container was not running yet), the pending action remains and the manual protect-container command always works.

Check the result#

After protecting a container, verify the wiring:

# The container carries the Imunify label
docker inspect <container> --format '{{ index .Config.Labels "imunify.ai.managed" }}'
# prints: 1

# Certificate trust is wired into the environment
docker exec <container> env | grep -c imunify-sensor
# prints a non-zero count

Then open the Panel: the container appears as a protected agent, and its HTTPS activity and agent actions start showing on the Events page. If something looks off, the Troubleshooting page covers sensor-side diagnostics.

To see any outstanding container-related reminders:

sudo imunify-agent-support list-pending

Undo it#

Protection is fully reversible:

# Remove Imunify settings from one container (recreates it back)
sudo imunify-agent-support unprotect-container <container-name-or-id>

# Remove Imunify settings from all managed containers on this host
sudo imunify-agent-support unprotect-all-containers

For a Compose service this removes the Imunify override file and recreates the service from your original definition.