Deploy Portainer Agent as a Compose service on the Docker host you want to manage. The standalone configuration needs the portainer/agent image, access to /var/run/docker.sock, access to the host’s Docker volume directory, and TCP port 9001 reachable from Portainer Server. After the container is running, add an Agent environment in Portainer using the host’s DNS name or IP address and port 9001.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
Use an external AGENT_SECRET when your Portainer Server is configured for secret authentication. For Docker Swarm, deploy the Agent as a global service on an overlay network and configure cluster discovery; publish port 9001 in host mode when the Server is outside the Swarm network.
As an Amazon Associate I earn from qualifying purchases.
Free tools Windows power users keep installed
One-click scans. No signup required.
What Portainer Agent does
Portainer Agent is a containerized API proxy for a Docker environment. Portainer Server connects to the Agent, and the Agent communicates with the Docker engine on its host. This lets one Portainer Server manage a remote Docker host without placing the Server itself on that host.
The Agent is not a replacement for Docker Engine and it does not create a separate container runtime. Its job is to expose the management connection that Portainer Server uses. The deployment therefore has two independent network paths to consider:
#1 Best Overall
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
- The Agent container must be able to reach the local Docker engine through the Docker socket.
- Portainer Server must be able to resolve and reach the Agent host on the Agent API port.
For a single, non-Swarm Docker host, Compose is the simplest placement model: one service runs on one host, and Portainer Server connects to that host’s address. Swarm uses a different model because every node needs an Agent task and the tasks must be discoverable across the cluster.
Choose the deployment model first
| Decision point | Standalone Docker with Compose | Docker Swarm |
|---|---|---|
| Scheduler | The Docker engine on one host; Compose starts one Agent service. | Swarm schedules the Agent as a global service. |
| Placement | One Agent container on the selected Docker host. | One Agent task on every Swarm node. |
| Networking | Publish the Agent port on the host so Portainer Server can reach it. | Use an overlay network for Agent-to-Agent discovery. Publish port 9001 in host mode when Portainer Server is outside the overlay. |
| Endpoint entered in Portainer | The host DNS name or IP address and the published Agent port. | An address reachable from the Server: a host address and published port from outside the Swarm, or an internal Swarm address when the Server shares the overlay. |
If you have one Docker host and do not need Swarm scheduling, use the standalone procedure below. If the environment is a Swarm, use the global-service procedure instead of running a single Compose container on one node.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Prerequisites for a standalone host
Before creating the service, confirm the following:
- Docker Engine is running on the target host.
- Docker Compose is available through the
docker composecommand. - You can create a directory for the Compose project and protect its environment file.
- The Portainer Server can route to the host over the network.
- A firewall or network policy can allow TCP 9001 from the Portainer Server to the Agent host.
The standard Agent image is portainer/agent. The standard deployment also assumes Docker stores named volumes under /var/lib/docker/volumes. If your Docker installation uses another host directory for volumes, substitute that directory on the left side of the bind mount while keeping /var/lib/docker/volumes as the container destination.
Deploy Portainer Agent with Docker Compose
1. Create a protected project directory
Create a directory on the Docker host for the Compose file and its environment file, then change into it:
mkdir -p ~/portainer-agent
cd ~/portainer-agentThe exact directory is not important. Keeping the Compose file and .env file together makes variable substitution predictable and keeps the deployment easy to inspect.
2. Store the optional secret outside the Compose file
If you use secret authentication, create a .env file in the project directory:
Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
AGENT_SECRET=replace-with-a-long-random-valueUse the same value when configuring the Portainer Server to require an Agent secret. Protect the file so only the account that manages the deployment can read it:
chmod 600 .envDo not commit this file to source control or paste the secret into shell history. If you are not using secret authentication, you can omit the variable from both the file and the Compose service.
3. Write the Compose file
Save the following as compose.yml:
services:
portainer-agent:
image: portainer/agent
restart: unless-stopped
environment:
AGENT_SECRET: ${AGENT_SECRET}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
ports:
- '9001:9001'Compose reads AGENT_SECRET from the adjacent .env file. The restart: unless-stopped policy brings the Agent back after a Docker or host restart unless you deliberately stopped it.
4. Start the Agent
From the project directory, create the container in detached mode:
docker compose up -dCheck that Compose reports the service as running:
docker compose psTo inspect startup messages if the service does not remain up, run:
docker compose logs --tail=100 portainer-agentThe service must be running before Portainer Server can establish an Agent connection. A container that repeatedly exits usually indicates a configuration, mount, or permission problem; resolve that locally before testing the remote connection.
Understand every port, mount, and variable
| Item | Purpose | Required in the standard standalone deployment? |
|---|---|---|
| TCP 9001 | The default Agent API port. The 9001:9001 mapping publishes the container port on the host. |
Yes, when Portainer Server reaches the Agent through the host network. |
AGENT_PORT |
Changes the port on which the Agent listens. | Optional. If changed, update the Compose port mapping and the address entered in Portainer. |
/var/run/docker.sock |
Lets the Agent communicate with the local Docker engine. | Yes. |
/var/lib/docker/volumes |
Exposes Docker’s volume directory so Portainer can manage volume-backed data. | Yes for the standard layout. |
AGENT_SECRET |
Authenticates connections when the Portainer Server is configured to require a matching secret. | Only when secret authentication is enabled. |
/:/host |
Exposes the host root filesystem inside the container for host-management features. | No; use only when those features are required. |
The Docker socket and volume bind mounts are host paths on the left and container paths on the right. Do not change the container destination for the volume directory. If the host keeps Docker volumes somewhere other than /var/lib/docker/volumes, change only the source path, for example:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Rank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
volumes:
- /your/docker-volume-directory:/var/lib/docker/volumesChanging the Agent port
The default is 9001. To use another port, set AGENT_PORT and publish the same listening port. For example:
services:
portainer-agent:
image: portainer/agent
restart: unless-stopped
environment:
AGENT_PORT: 9100
AGENT_SECRET: ${AGENT_SECRET}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
ports:
- '9100:9100'After recreating the service, enter the new port in Portainer’s environment-add form and allow that port through the firewall. A mismatch between the listening port, published port, and Portainer endpoint produces a connection failure even when the container is healthy.
Connect the Agent to Portainer Server
- Open Portainer Server’s environment-add flow.
- Choose the Agent environment type.
- Enter the DNS name or IP address of the Docker host running the Agent.
- Enter
9001, unless you changedAGENT_PORT. - If the Server is configured to require a secret, provide the exact same
AGENT_SECRETvalue used by the Agent. - Submit the environment and wait for Portainer to test the connection.
The address must be resolvable and reachable from the Portainer Server itself, not merely from your laptop. If you use a hostname, verify that the Server’s DNS configuration resolves it to the intended host. If the Server runs in another network, check routing and firewall rules between that network and the Agent host.
Secure the connection and the Docker host
Limit network exposure
Port 9001 is the Agent API endpoint. Publish it only where the Portainer Server needs access; a firewall rule that permits the Server’s address or network is preferable to an unrestricted Internet exposure. In a private network, keep the Agent host on the intended management segment and verify that no unrelated systems can reach the published port.
Use a matching secret when required
Portainer supports secret-based authorization between Server and Agent. The values must match exactly. A typo, extra whitespace, or an updated value on only one side causes authentication to fail even if TCP connectivity is working. When changing a secret, coordinate the Server and Agent configuration and restart or recreate the service so both sides use the new value.
Treat the Docker socket as privileged access
Mounting /var/run/docker.sock gives the Agent the channel it needs to manage the local Docker environment. Store the Compose project and its environment file with appropriate filesystem permissions, and limit who can administer the host. Do not add the host-root mount unless you need host-management functions.
Enable host-management features only when needed
Host-management features are disabled by default. To enable them, add the capability variable and host-root bind mount:
Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
services:
portainer-agent:
image: portainer/agent
restart: unless-stopped
environment:
AGENT_SECRET: ${AGENT_SECRET}
CAP_HOST_MANAGEMENT: 1
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
- /:/host
ports:
- '9001:9001'CAP_HOST_MANAGEMENT=1 and /:/host give the Agent the access required for host filesystem and hardware operations. Because the mount exposes the host root to the container, enable this combination only for an environment that actually uses those operations. For ordinary container and volume management, leave both settings out.
Deploy the Agent across a Docker Swarm
A Swarm needs an Agent on every node that Portainer may manage. Deploy the Agent as a global service rather than as a single replicated service. Attach it to an overlay network so Agent tasks can discover one another.
Swarm Compose file
The following is a representative stack definition. The tasks.portainer-agent:9001 value follows the documented discovery pattern tasks.<AGENT_SERVICE_NAME>:<AGENT_PORT>; if you rename the service or change its port, change the discovery address accordingly.
services:
portainer-agent:
image: portainer/agent
environment:
AGENT_CLUSTER_ADDR: tasks.portainer-agent:9001
AGENT_SECRET: ${AGENT_SECRET}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- /var/lib/docker/volumes:/var/lib/docker/volumes
networks:
- agent_overlay
deploy:
mode: global
ports:
- target: 9001
published: 9001
protocol: tcp
mode: host
networks:
agent_overlay:
driver: overlayAGENT_CLUSTER_ADDR is mandatory for clustered Agent discovery. The global deployment mode schedules one task on each Swarm node. The socket and volume mounts are host-local, so each node must have the expected Docker paths or an equivalent volume-directory source.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Deploy the stack
From a Swarm manager, save the file as agent-stack.yml and deploy it:
docker stack deploy -c agent-stack.yml portainer-agentInspect the service and its tasks:
docker stack services portainer-agent
docker service ps portainer-agent_portainer-agentWhen Portainer Server runs outside the Swarm overlay, keep the host-mode publication and connect to a Swarm node’s DNS name or IP on port 9001. When the Server and Agents share the overlay, internal networking may be sufficient and a public host publication may not be necessary; use an internal address that the Server can resolve and reach in that design.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot in the order that removes the most uncertainty
1. Confirm the container or task is running
For Compose, run docker compose ps and inspect docker compose logs portainer-agent. For Swarm, check docker service ps and confirm every expected node has a running global task. Fix image, configuration, or restart errors before testing DNS or firewall access.
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
2. Confirm mounts and permissions
On the host, verify that /var/run/docker.sock exists and that the Docker volume directory used in the Compose file is present. A non-standard volume location must appear as the source path while the container destination remains /var/lib/docker/volumes. Review container logs for mount or access errors.
Recommended Free Tools
3. Test the network path to the Agent port
From the Portainer Server host or container network, test the Agent host and port. For example:
getent hosts agent-host.example
nc -vz agent-host.example 9001These checks separate a routing or firewall problem from an Agent configuration problem. If the port is closed, inspect the Compose port mapping, Swarm publication mode, host firewall, and any network policy between Server and Agent.
4. Verify name resolution from the Server
A hostname that resolves on your workstation may fail inside the Portainer Server container or on the Server host. Resolve the exact hostname entered in Portainer from the Server’s network context. If it resolves to the wrong address, use the correct DNS record or a reachable IP address.
5. Compare secrets exactly
If TCP connectivity succeeds but Portainer reports authorization failure, compare the Server and Agent AGENT_SECRET values byte for byte. Check for a stale container that was not recreated after editing .env, an extra space in the value, or a different secret on one Swarm node. Recreate the service after correcting the value.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Operational changes after deployment
Moving Docker’s volume directory
If Docker uses a non-standard volume location, edit only the host-side source in the bind mount, then recreate the service. Keep the destination /var/lib/docker/volumes so the Agent sees the expected container path.
Changing the port
Set AGENT_PORT, update the published port, adjust firewall rules, recreate the service, and edit the Portainer environment endpoint. Perform all changes together so Portainer does not continue trying the old endpoint.
Changing the secret
Update the secret where the Server requires it and in the Agent’s environment source, then recreate or restart the Agent. A temporary mismatch is expected to make the environment unavailable until both sides carry the same value.
Updating the service definition
Keep the Compose file as the authoritative description of the service. After edits, run docker compose up -d again so Compose applies the changed environment, mounts, or port mapping. In Swarm, redeploy the stack from the manager with docker stack deploy.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsQuick Recap
Standalone Compose checklist
- The service uses the
portainer/agentimage and an automatic restart policy. /var/run/docker.sockis mounted into the container.- The host Docker volume directory is mounted at
/var/lib/docker/volumes. - TCP 9001 is published and reachable from Portainer Server, unless you deliberately changed
AGENT_PORT. - The Agent container is running and its logs show no startup errors.
- The Server uses the Agent host’s resolvable DNS name or IP address.
- Both sides use the same
AGENT_SECRETwhen secret authentication is enabled. CAP_HOST_MANAGEMENT=1and/:/hostare present only when host-management features are required.
Swarm checklist
- The Agent is deployed in global mode.
- Every node has the required Docker socket and volume-directory mounts.
- An overlay network connects the Agent tasks.
AGENT_CLUSTER_ADDRuses thetasks.<AGENT_SERVICE_NAME>:<AGENT_PORT>discovery pattern.- Port 9001 is published in host mode when the Server is outside the overlay.
- The endpoint entered in Portainer is reachable from the Server’s actual network context.
- Secret values match on the Server and all Agent tasks when authentication is enabled.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
