iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
Deploy Portainer Agent as a Compose service on the Docker host you want to manage. The service needs access to the host Docker socket and Docker’s volume directory. When the Portainer Server connects over the host network, publish TCP port 9001 (the default Agent API port), then add the host’s DNS name or IP address and that port in Portainer’s environment-add flow.
The procedure below covers a single Docker host, a Docker Swarm cluster, secret authentication, optional host-management features, and the checks that usually explain a failed connection.
What Portainer Agent does
Portainer Agent is a containerized API proxy. It runs beside Docker and exposes the operations that a Portainer Server uses to manage that Docker environment. The Agent is not a replacement for Docker Engine: the Engine still runs containers, images, networks, and volumes, while the Agent provides the connection point for the Server.
For a standalone host, one Agent service is enough. In Swarm, the Agent is deployed globally so every node has a local task. The networking and address that you enter in Portainer therefore depend on which Docker mode you use.
#1 Best Overall
- Powerful Turbo Fan:CAGIWIRU Electric Air Duster have reached speed up to 130000RPM,Can efficient remove dust and debris.With LED light and Three Adjustable Speed to meet with different cleaning tasks.
- With Attached USB C Fasting Charging cable.Charing 3 hours,Enjoy up to 240 minutes of use on the lowest setting, For third speed can use for 25mins.with four charging options to meet with your needs.
- Wide Application:Upgraded attached 5 different nozzles,making it suitable for a variety of scenes, such as car,pet, pc, keyboards, and other electronic devices. It also serves for office and home clean duster.
- Handy Design & Portable:Cordless air duster electric nozzle is Light weight and small size, design and comfortable to hold and space saving, convenient to carry around. You can put it in your room or inside the car without taking up space.
- Warranty & Support: Our Electric air duster comes with 5 years warranty and 24/7 customer service. During this period, if you have any questions,pls kindly feel free to contact us.
Choose the deployment model first
| Decision point | Standalone Docker host | Docker Swarm |
|---|---|---|
| Scheduler | The regular Docker Compose service scheduler on one host | Swarm scheduler |
| Placement | One Agent container on the selected host | A global service task on every Swarm node |
| Networking | Publish the Agent’s host port when the Server connects across the network | Use an overlay network; publish port 9001 in host mode when the Server is outside the overlay |
| Endpoint entered in Portainer | Agent host DNS name or IP plus the published port | An address reachable through the Swarm network; use the host address and port when the Server is outside the overlay |
| Cluster discovery | Not required | AGENT_CLUSTER_ADDR is mandatory for clustered Agent discovery and follows tasks.<AGENT_SERVICE_NAME>:<AGENT_PORT> |
If you are managing one independent Docker server, use the standalone file in the next section. Do not deploy a global Swarm service on a host that is not part of a Swarm.
Prerequisites and network planning
- A Docker Engine installation with the Docker Compose plugin (the
docker composecommand). - Permission to create containers, bind-mount the Docker socket, and read the host Docker volume directory.
- A Portainer Server that can resolve and reach the Agent host. The Server must be able to open a TCP connection to the Agent endpoint through firewalls and network policies.
- A decision about whether to require an Agent secret. If secret authentication is enabled, the Server and Agent values must match exactly.
The Docker socket and the volume-directory mount are functional requirements, not optional conveniences for a normal standalone deployment. Keep the Compose project in a protected directory because it contains the path to a high-privilege Docker control interface and may contain a secret file.
Deploy the Agent on one Docker host
1. Create a protected Compose directory
Choose a directory on the host, change into it, and create an .env file that only administrators can read. The Compose file below expects the variable AGENT_SECRET to be supplied from that file or from the shell environment.
mkdir -p /opt/portainer-agent
cd /opt/portainer-agent
umask 077
nano .envPut a long, unique value in the file:
AGENT_SECRET=replace-with-a-long-random-valueAfter saving, verify that the file is not world-readable. Do not commit it to source control or paste the value into tickets and chat. If you are not using secret authentication, remove the AGENT_SECRET setting from both the Agent and the Server configuration instead of leaving a shared placeholder.
Rank #2
- Screen Cleaner is Your Screen’s New Bestfriend! - EVEO is proud to present a screen cleaner that’s perfectly suited for your TV. Meet your new screen cleaner, computer screen cleaner, laptop cleaner, iPad cleaner, Macbook,tv cleaner or any other electronic device. Our screen cleaner spray and wipe along with the included plush microfiber cloth, easily removes dust, fingerprints & other smudges on the screen’s surface. Clean effectively for a streak-free screen
- Gentle on your Screens - Our screen cleaner spray and wipes is compatible to be used even for the most sensitive LCD, LED, CRT, and OLED screens in proper use. Be at ease knowing that this product is compatible with all the major brands: LG, SONY, Samsung, Sharp, iPad, iPhone, Android screens, Kindle, PC monitors - we’ve got you covered! Can be used as LCD screen cleaner, tv cleaner, smart tv screen cleaner, and more
- Premium Super Soft Plush Microfiber Cloth - Included in this efficient screen cleaning kit. This screen cleaner spray and wipe has our signature plush microfiber cloth specially designed to comply with screens and monitors and leave them streak-free. Has been shown to effectively absorbs stubborn stains, zero streaks, and no fiber shedding. Always use this together with our screen cleaner for the best results
- Easy-to-Use Screen Cleaner Kit + microfiber cleaning cloth - The EVEO Screen Cleaning Kit will easily be your new favorite tool when it comes to taking care of the things you love most, quick and easy solution for a streak-free screen. Simply screw on the sprayer gun on the screen cleaner bottle. Spray the cleaning liquid onto the microfiber cloth, then wipe the screen until desired cleanliness & shine is achieved.
- Quality Screen Care Kit Worth Purchasing - Enjoy a convenient Screen Cleaner anytime, anywhere you need it. Your satisfaction is our top priority. We stand behind the quality of our products and that’s why, you shouldn’t be worrying at all. We manufacture the Best Screen Cleaner. and can be used for laptop cleaning kit, laptop screen cleaner, tv screen cleaner for smart tv. MacBook screen cleaner, monitor cleaner or screen cleaner spray for electronic devices with microfiber cleaning cloth
2. Write the Compose file
Save this as compose.yaml in the same directory:
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'Each line has a specific purpose:
image: portainer/agentselects the Agent image. If your organization uses a pinned image tag, place that tag after the image name according to your change-control policy.restart: unless-stoppedbrings the Agent back after a crash or host restart, while still allowing an administrator to stop it intentionally./var/run/docker.sock:/var/run/docker.sockgives the Agent its Docker Engine API connection./var/lib/docker/volumes:/var/lib/docker/volumeslets the Agent see Docker-managed volumes. The container-side destination must remain/var/lib/docker/volumes.9001:9001publishes TCP 9001 on the host and forwards it to the Agent’s default API port. The left side is the host port; the right side is the container port.AGENT_SECRETcarries the value used for secret authentication. Configure the identical value on the Portainer Server when that protection is required.
3. Start and inspect the service
Run the Compose project from the directory containing compose.yaml and .env:
docker compose up -d
docker compose ps
docker compose logs --tail=100 portainer-agentThe service should show a running state. Logs should not report a missing socket, an unreadable volume path, or a configuration error. If the container exits, inspect the complete log with docker compose logs portainer-agent before trying to connect it in Portainer.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Connect the host to Portainer Server
- Open the Portainer Server environment-add flow.
- Choose the Agent environment type.
- Enter the DNS name or IP address of the Docker host running the Agent.
- Enter port
9001, unless you deliberately changed the Agent port withAGENT_PORTand published the corresponding host port. - If secret authentication is enabled, configure the Server with the exact same
AGENT_SECRETvalue used by the Agent. - Submit the environment and wait for Portainer to test the connection.
The hostname is resolved from the Portainer Server’s network location, not from your workstation’s browser. A name that works on your laptop can still fail if the Server container or Server host cannot resolve it. Likewise, a firewall must allow the Server’s source address to reach the published Agent port.
Change the Agent port safely
The default Agent API port is 9001. You can change the listening port with AGENT_PORT, but every dependent setting must change together:
Rank #3
- 【Large size】：Measuring 800 x 300 mm/ 31. 5×12 inches, which is wider and taller than others. Large mouse pad can perfectly fit your keyboard and mouse of any size, and there is also ample space for peripherals such as phones, tablets, etc.
- 【LED backlight mouse pad】：Blade Hawks RGB mouse pad provides 7 static modes and 7 dynamic modes will give you the options you are looking for. Power-off memory function remembers the last lighting mode you selected. The super glow fiber Chroma will give you a colorful gaming setup that you want.
- 【Anti-slip rubber base】：Made from Natural rubber, this gaming mousepad will firmly grip your desktop, allowing you to enjoy the ultimate precision in the games you are most passionate about. It also comes with a texture that enhances this ability even further.
- 【Smooth and waterproof surface】: Micro-textured cloth surface, for extremely precise mouse control and a smooth movement. When liquid splashes on the gaming mouse pad, it forms water droplets and slides down. Will not delay your work or gameplay.
- 【Plug and play】: This mouse and keyboard pad is powered by USB, plug and play, no driver required. One button control light modes. Press one time to change the lighting mode, press twice to change the brightness, press and hold about 3 seconds turn ON/OFF.
- Set
AGENT_PORTin the Agent service environment. - Publish the chosen host port to that container port in Compose.
- Use the chosen host port in Portainer’s Agent endpoint.
- For Swarm discovery, use the same value in
AGENT_CLUSTER_ADDR. - Update firewall and network-policy rules for the new port.
Leaving one of these values at 9001 while changing another produces a connection failure that can look like a firewall problem.
Deploy the Agent across a Docker Swarm
Swarm requires one Agent task per node, so use a global service and an overlay network. The following stack illustrates the required shape. Replace the service name and secret handling with the names used in your cluster.
Recommended Free Tools
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-net
ports:
- target: 9001
published: 9001
protocol: tcp
mode: host
deploy:
mode: global
networks:
agent-net:
driver: overlayWhy the Swarm settings differ
deploy.mode: globalschedules an Agent task on every Swarm node rather than placing a single replica on one node.- The overlay network allows Agent tasks to communicate through Swarm networking.
AGENT_CLUSTER_ADDRis mandatory for clustered Agent discovery. The documented pattern istasks.<AGENT_SERVICE_NAME>:<AGENT_PORT>; with the example service name and default port, that becomestasks.portainer-agent:9001.- The long-form port declaration uses host mode. Keep it when the Portainer Server is outside the Swarm overlay and must reach a node’s host address. If Server and Agents share the overlay, internal networking may be sufficient and an external host-port publication may not be necessary.
Create the stack’s overlay network as part of the stack definition or use an existing overlay network that your deployment policy permits. Deploy from a Swarm manager:
docker stack deploy -c compose.yaml portainer-agent
docker service ls
docker service ps portainer-agentWhen adding the Swarm environment in Portainer, choose the Agent environment type and enter an address that is reachable in the topology you selected. An external Server normally uses a Swarm node’s DNS name or IP and the published port; a Server connected to the overlay can use the internal service-discovery path where supported by that arrangement.
Rank #4
- 【Softer and More Comfortable】Vaydeer wrist rest has unique diamond pattern, which is the combination of softness and aesthetics. The materials of wrist rest are improved into higher quality memory foam and covered with silky smooth lycra. The computer wrist rest makes you as comfortable and cushiony as like rest your wrists on clouds.
- 【Ergonomic Wrist Saver】The wrist rests for keyboard and mouse comes with a 17.32×3.15×0.83 inch keyboard wrist pad and a 5.94×3.15×0.83 inch mouse wrist support. Based on ergonomic design, the unique concave shape is the perfect fit for your wrist joints. The wrist rest pad fits most computer keyboards and laptops, improve hand and wrist posture, release your wrist and arm stress.
- 【Non-Slip Rubber Bottom】Featuring an anti-skid silicone base on the bottom, this wrist keyboard support stays firmly in place on your desk, preventing the padding from sliding around, ensuring stable and consistent wrist support during extended computer sessions.
- 【Better Experience & Pain Relief】Our keyboard arm rest is beneficial to alleviate the soreness caused by direct contact and friction between your arm and a hard desk surface, reducing the risk of wrist fatigue or carpal tunnel. The soft texture of memory foam can evenly distribute the pressure around your wrists and provide good support with just enough give.
- 【Helpful in Multiple Scenarios】Whether you're working, studying, writing, typing, gaming, this keyboard and mouse rest combo is an essential accessory to add comfort and support to your hands and wrists. It’s also a great gift for men, women, family, friend, coworker, gamer, teacher, etc.
Mount paths and non-standard Docker data roots
The example assumes Docker stores managed volumes under /var/lib/docker/volumes. If the daemon uses a different data-root, change only the host-side source of the bind mount and keep the destination inside the container unchanged. For example, if the host’s volume directory is /srv/docker/volumes, use:
PC 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 & 11Outdated 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 match- /srv/docker/volumes:/var/lib/docker/volumesDo not replace the Docker socket mount with a socket from an unrelated daemon, and do not map the volume directory to a different container destination unless the Agent documentation for your chosen image explicitly requires it. A missing or incorrect volume mount can allow a connection while preventing Portainer from displaying or operating on Docker volumes correctly.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Enable host-management features only when needed
Host-management features are disabled by default. To enable them, add CAP_HOST_MANAGEMENT=1 and bind-mount the host root at /:/host:
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
- /:/hostThis gives the Agent access needed for host filesystem and hardware operations. It also materially expands what a compromised or misconfigured Agent could inspect or change. Leave the capability and root mount out of the service unless you specifically need those host-management functions, and review the additional access with your security administrator before enabling it.
Best Value
- 【No Drill Mounted】Cable management tray can be assembled in as little as 3 minutes or less-simply. Side clips easily clampe the edge of desk, pass through the holes on the sides, and secure excess cables with baskets. Desk cable management supports inward or outward installation to meet your needs in different scenarios, and provides you with great convenience when collecting and organizing wires.
- 【Rubber Pad Protects Desk】Wire organizer under desk built-in soft rubber pads on the clamp protect your desk from scratches, so you will not damage your furniture or office.
- 【Sturdy and Beautiful】Cord management under desk is made of high-quality carbon steel and holds about 15 lbs. The wire basket has 2 holes on each side of the tray to enable your cables to pass freely. Cable baskets are suitable for desk thickness use from 0.4" to 2.4".
- 【Space Saving & Keep Organized】Desk cable management tray holds all your power cords, outlet strips, USB hubs and computer transformers hidden from your feet, and the data cables will not enter the vacuum cleaner to keep your desk clean and tidy. Desk wire organizer is also suitable for use in the kitchen and outdoors.
- 【Reduce Safety Risks】Cable tray under desk keeps all plugs away from your kids, no more worry about tripping. Using 2 holes wire tray saves extra space, helps you easily cabling and wire protection. The mesh design is not easy to accumulate dust, but avoids safety accidents caused by messy wires.
Security and operational practices
- Restrict the published Agent port with host firewall rules or network policy so only the Portainer Server can reach it.
- Use a unique, protected
AGENT_SECRETfor each security boundary where practical, and update both sides together during rotation. - Protect the Compose directory and especially the
.envfile. A readable secret defeats the purpose of secret authentication. - Treat access to
/var/run/docker.sockas privileged access to the Docker host. Limit shell and file access to trusted administrators. - Keep the Agent image and Compose definition under the same change-management process as the Portainer Server. Test upgrades on a non-production host when your operational policy requires it.
- Record the actual host address, published port, and any non-default
AGENT_PORTso future firewall or DNS changes do not silently break the environment.
Troubleshoot in the order that isolates the fault
1. Confirm that the Agent is running
For Compose, run docker compose ps and inspect docker compose logs portainer-agent. For Swarm, run docker service ps portainer-agent and verify that every expected node has a running task. A stopped or repeatedly restarting task must be fixed before network testing is meaningful.
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 errors2. Check both required mounts
Confirm that /var/run/docker.sock exists on the host and that the Docker volume directory is the actual data-root path. Check the container’s mount list with:
docker inspect portainer-agentFor a Swarm task, inspect the service definition and the task’s node. Permission errors, a typo in the source path, or a non-standard Docker root are common causes of an Agent that starts but cannot manage resources.
3. Test TCP reachability from the Server side
From the Portainer Server host or container network, test the Agent host and port with the networking tools available in your environment. Verify that the host firewall, cloud security group, container network policy, and any intervening firewall all permit the Server-to-Agent connection. In Swarm, also verify that the overlay network is attached to the service and that the selected endpoint matches whether the Server is inside or outside that overlay.
4. Verify name resolution
Resolve the configured DNS name from the Portainer Server’s own network namespace. If resolution fails there, use a DNS name visible to that network or enter a reachable IP address. Avoid testing only from a desktop browser, which may use a different resolver and routing path.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →5. Compare secret values exactly
If secret authentication is enabled, compare the Agent’s AGENT_SECRET and the Server’s configured value character for character. Check for trailing spaces, different capitalization, an unsourced .env file, or a stale container that was not recreated after the secret changed. Recreate the service after correcting the value:
docker compose up -d --force-recreate6. Recheck every changed port
When AGENT_PORT is non-default, confirm the container listening port, Compose publication, Swarm discovery address, Portainer endpoint, and firewall rule all use the same number. A single mismatch is enough to produce a timeout or connection-refused error.
Quick Recap
Standalone Compose checklist
- The service uses
portainer/agentand is running with a restart policy. - The Docker socket is mounted at both the host and container path
/var/run/docker.sock. - The host Docker volume directory is mounted to container path
/var/lib/docker/volumes. - TCP 9001 is published when the Server reaches the Agent over the host network, or the chosen
AGENT_PORTis published instead. - The Server can resolve and reach the configured host address.
- Matching secret values are configured when secret authentication is enabled.
- Host-management capability and
/:/hostare absent unless those features are required.
Swarm checklist
- The Agent is deployed as a global service so every node receives a task.
- The service is attached to an overlay network.
AGENT_CLUSTER_ADDRuses thetasks.<AGENT_SERVICE_NAME>:<AGENT_PORT>pattern.- Port 9001 is published in host mode when an external Server needs to reach nodes directly.
- The Portainer endpoint matches the actual Server-to-Agent network path.
- Every node’s task has the required socket and volume-directory mounts.
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.
