{"id":34815986,"url":"https://github.com/solutionforest/simple-docker-agent","last_synced_at":"2026-03-27T05:05:34.692Z","repository":{"id":291769541,"uuid":"978491530","full_name":"solutionforest/simple-docker-agent","owner":"solutionforest","description":"A lightweight Python-based agent that provides real-time monitoring of Docker containers and host system resources.","archived":false,"fork":false,"pushed_at":"2025-05-06T12:17:24.000Z","size":35,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T13:29:01.352Z","etag":null,"topics":["docker","docker-agent","docker-monitoring","monitoring"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solutionforest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-06T04:25:31.000Z","updated_at":"2025-05-06T12:53:37.000Z","dependencies_parsed_at":"2025-05-07T06:15:07.794Z","dependency_job_id":null,"html_url":"https://github.com/solutionforest/simple-docker-agent","commit_stats":null,"previous_names":["solutionforest/simple-docker-agent"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/solutionforest/simple-docker-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solutionforest%2Fsimple-docker-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solutionforest%2Fsimple-docker-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solutionforest%2Fsimple-docker-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solutionforest%2Fsimple-docker-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solutionforest","download_url":"https://codeload.github.com/solutionforest/simple-docker-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solutionforest%2Fsimple-docker-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31022427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T04:58:43.976Z","status":"ssl_error","status_checked_at":"2026-03-27T04:58:17.966Z","response_time":164,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-agent","docker-monitoring","monitoring"],"created_at":"2025-12-25T13:38:28.486Z","updated_at":"2026-03-27T05:05:34.685Z","avatar_url":"https://github.com/solutionforest.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![image](https://github.com/user-attachments/assets/c6066ec1-a2d8-4d66-b925-6405558d08e3)\n\n# Simple Docker Agent\n\nA lightweight Python-based agent that provides real-time monitoring of Docker containers and host system resources.\n\n## Features\n\n- **REST API**: Exposes a `/status` endpoint for easy integration.\n- **Container Insights**: Reports CPU, memory (raw and humanized), uptime, ports, labels, and more for each container.\n- **Host Metrics**: Shows CPU, memory, and disk usage for the host (raw and humanized).\n- **Fast \u0026 Lightweight**: Designed for quick responses, even with many containers.\n- **Easy Deployment**: Runs as a Docker container with minimal configuration.\n\n## Screenshot\n\n![image](https://github.com/user-attachments/assets/b7a1f2dc-6f58-4edc-bb29-ba92002c26a5)\n![image](https://github.com/user-attachments/assets/3960da14-9f7a-4b45-8e46-90d84ddcbb21)\n\n\n---\n\n## Quick Start\n\n## Run from Docker Hub (method 1)\n\nYou can run the latest public version of **Simple Docker Agent** directly from Docker Hub, with no need to build the image yourself.\n\n```bash\ndocker pull solutionforest/simple-docker-agent:latest\n\ndocker run -d \\\n  --name simple-docker-agent \\\n  -p 8080:8080 \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  --privileged \\\n  solutionforest/simple-docker-agent:latest\n```\n\n- The agent will now be accessible at [http://localhost:8080/status](http://localhost:8080/status).\n- Make sure to mount the Docker socket (`-v /var/run/docker.sock:/var/run/docker.sock`) to allow the agent to access container information.\n- The `--privileged` flag may be required for collecting some host metrics.\n\nYou can also specify a version instead of `latest`, for example:\n\n```bash\ndocker pull solutionforest/simple-docker-agent:1.0.0\ndocker run -d \\\n  --name simple-docker-agent \\\n  -p 8080:8080 \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  --privileged \\\n  solutionforest/simple-docker-agent:1.0.0\n```\n\n**See [solutionforest/simple-docker-agent on Docker Hub](https://hub.docker.com/r/solutionforest/simple-docker-agent) for available tags and more info.**\n\n\n### 1. Build the Agent Docker Image (method 2)\n\n```bash\ngit clone https://github.com/solutionforest/simple-docker-agent\ncd simple-docker-agent\ndocker build -t simple-docker-agent .\n```\n\n### 2. Run the Agent\n\n```bash\ndocker run -d \\\n  --name docker-agent \\\n  -p 8080:8080 \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  --privileged \\\n  simple-docker-agent\n```\n\n### 3. Query the Status API\n\n```bash\ncurl http://localhost:8080/status | jq\n```\n\n---\n\n## Example Response\n\n```json\n{\n  \"host\": {\n    \"cpu_percent\": 4.5,\n    \"memory\": {\n      \"total\": 16777216000,\n      \"used\": 2548039680,\n      \"percent\": 15.2,\n      \"total_human\": \"16.8 GB\",\n      \"used_human\": \"2.5 GB\"\n    },\n    \"disk\": {\n      \"total\": 128849018880,\n      \"used\": 64424509440,\n      \"percent\": 50.0,\n      \"total_human\": \"128.8 GB\",\n      \"used_human\": \"64.4 GB\"\n    }\n  },\n  \"docker_services\": [\n    {\n      \"id\": \"abcdef123456...\",\n      \"name\": \"my-service\",\n      \"status\": \"running\",\n      \"image\": [\"nginx:latest\"],\n      \"stats\": {\n        \"cpu_percent\": 0.21,\n        \"cpu_human\": \"0.21%\",\n        \"mem_usage_bytes\": 25600000,\n        \"mem_usage_human\": \"25.6 MB\",\n        \"mem_limit_bytes\": 2147483648,\n        \"mem_limit_human\": \"2.1 GB\"\n      },\n      \"created_at\": \"2024-05-01T12:00:00Z\",\n      \"started_at\": \"2024-05-01T12:01:00Z\",\n      \"uptime_seconds\": 3600,\n      \"uptime_human\": \"1 hour\",\n      \"restart_count\": 0,\n      \"ports\": {\n        \"80/tcp\": [\n          {\n            \"HostIp\": \"0.0.0.0\",\n            \"HostPort\": \"8081\"\n          }\n        ]\n      },\n      \"labels\": {\n        \"com.docker.compose.project\": \"myproject\"\n      }\n    }\n    // ...more containers\n  ]\n}\n```\n\n---\n\n## Web Dashboard\n\nA modern, interactive dashboard UI is included! Just open:\n\n    http://localhost:8080/dashboard.html\n\nin your browser after starting the agent. No extra setup is required.\n\n### Dashboard Features\n- **System Overview**: Uptime, CPU idle %, core count, memory, swap, and disk usage cards.\n- **Charts**: Real-time graphs for system load, CPU modes, memory, disk IO, network, and swap.\n- **Container Selector**: Switch between running containers to view their stats.\n- **Per-Container Stats**: Status, image, uptime, restart count, ports, and resource usage (CPU %, memory MB) with historical charts.\n- **Responsive Design**: Works on desktop and mobile.\n\n---\n\n## API\n\n- **/status**: Returns a JSON object with host and container stats. See example above for structure.\n- **/dashboard.html**: Serves the dashboard UI.\n\n---\n\n## Running Without Docker (Advanced)\n\nYou can run the agent directly with Python 3.8+ (Linux recommended):\n\n```bash\npip install flask psutil docker humanize\npython agent.py\n```\n\nThen visit http://localhost:8080/dashboard.html in your browser.\n\n---\n\n## Configuration\n\n- **Port**: Default is `8080` (see `agent.py`).\n- **Docker socket**: Mount `/var/run/docker.sock` for API access.\n- **Privileges**: The container may require `--privileged` for resource stats.\n\n---\n\n## Security\n\n**Do not expose the agent’s API to the public internet without authentication or firewall protection.**  \nFor production deployments, consider running behind a reverse proxy and securing the endpoint.\n\n---\n\n## License\n\nMIT License\n\n---\n\n## Credits\n\n- [psutil](https://github.com/giampaolo/psutil)\n- [docker-py](https://github.com/docker/docker-py)\n- [humanize](https://github.com/jmoiron/humanize)\n- [Flask](https://github.com/pallets/flask)\n\n---\n\n## Contributing\n\nPull requests and feature suggestions are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolutionforest%2Fsimple-docker-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolutionforest%2Fsimple-docker-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolutionforest%2Fsimple-docker-agent/lists"}