{"id":46523962,"url":"https://github.com/flatrun/agent","last_synced_at":"2026-06-08T03:04:18.401Z","repository":{"id":324978553,"uuid":"1098320598","full_name":"flatrun/agent","owner":"flatrun","description":"Lightweight Go agent for flatfile-based Docker Compose deployment management via REST API","archived":false,"fork":false,"pushed_at":"2026-06-06T16:29:48.000Z","size":736,"stargazers_count":7,"open_issues_count":35,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T17:14:32.781Z","etag":null,"topics":["containers","docker","docker-compose","docker-management","docker-ui","orchestration-framework","server","server-management"],"latest_commit_sha":null,"homepage":"https://flatrun.dev","language":"Go","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/flatrun.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-17T14:40:34.000Z","updated_at":"2026-05-30T12:50:32.000Z","dependencies_parsed_at":"2026-01-04T03:01:49.139Z","dependency_job_id":null,"html_url":"https://github.com/flatrun/agent","commit_stats":null,"previous_names":["flatrun/agent"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/flatrun/agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatrun%2Fagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatrun%2Fagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatrun%2Fagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatrun%2Fagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatrun","download_url":"https://codeload.github.com/flatrun/agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatrun%2Fagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34046005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["containers","docker","docker-compose","docker-management","docker-ui","orchestration-framework","server","server-management"],"created_at":"2026-03-06T20:03:18.058Z","updated_at":"2026-06-08T03:04:18.396Z","avatar_url":"https://github.com/flatrun.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlatRun Agent\n\nLightweight Go agent for flat-file container orchestration.\n\n## Overview\n\nFlatRun Agent is the backend service that manages Docker deployments through a simple filesystem-based approach. It monitors your deployments directory and provides a REST API for the FlatRun UI.\n\n## Features\n\n- Docker Compose deployment management\n- Container lifecycle control (start, stop, restart)\n- Real-time container monitoring and logs\n- Docker resource management (images, volumes, networks)\n- SSL certificate monitoring\n- Quick App templates for rapid deployment\n- JWT-based API authentication\n- Health monitoring and statistics\n\n## Installation\n\n### Prerequisites\n\n- Go 1.21+ (for building from source)\n- Docker \u0026 Docker Compose v2\n- Access to Docker socket (`/var/run/docker.sock`)\n- Linux server (Ubuntu 20.04+, Debian 11+, or similar)\n\n### Option 1: Build from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/flatrun/agent.git\ncd agent\n\n# Install dependencies and build\nmake build\n\n# Or manually:\ngo mod download\ngo build -o flatrun-agent ./cmd/agent\n```\n\n### Option 2: Download Binary\n\n```bash\n# Download the latest release (when available)\nwget https://github.com/flatrun/agent/releases/latest/download/flatrun-agent\nchmod +x flatrun-agent\n```\n\n## Configuration\n\n1. Copy the example configuration:\n\n```bash\ncp config.example.yml config.yml\n```\n\n2. Edit `config.yml`:\n\n```yaml\ndeployments_path: /home/user/deployments\ndocker_socket: unix:///var/run/docker.sock\n\napi:\n  host: 0.0.0.0\n  port: 8090\n  enable_cors: true\n  allowed_origins:\n    - http://localhost:5173\n    - http://localhost:3000\n\nauth:\n  enabled: true\n  api_keys:\n    - \"your-secure-api-key-here\"\n  jwt_secret: \"generate-a-secure-random-string-here\"\n\nnginx:\n  container_name: nginx\n  config_path: /deployments/nginx/conf.d\n  reload_command: nginx -s reload\n\ncertbot:\n  container_name: certbot\n  email: your-email@example.com\n  staging: true\n\nlogging:\n  level: info\n  format: json\n\nhealth:\n  check_interval: 30s\n  metrics_retention: 24h\n```\n\n### Key Configuration Options\n\n- **deployments_path**: Directory where your docker-compose deployments are stored\n- **api.port**: Port the API server listens on (default: 8090)\n- **auth.api_keys**: List of valid API keys for authentication\n- **auth.jwt_secret**: Secret key for signing JWT tokens (generate a secure random string)\n\n## Running the Agent\n\n### Development Mode\n\n```bash\n# Using make\nmake run\n\n# Or directly\n./flatrun-agent --config config.yml\n```\n\n### Production Setup with Systemd\n\n1. Move the binary to a system location:\n\n```bash\nsudo mv flatrun-agent /usr/local/bin/\nsudo chmod +x /usr/local/bin/flatrun-agent\n```\n\n2. Create a systemd service file:\n\n```bash\nsudo nano /etc/systemd/system/flatrun-agent.service\n```\n\n```ini\n[Unit]\nDescription=FlatRun Agent\nAfter=network.target docker.service\nRequires=docker.service\n\n[Service]\nType=simple\nUser=root\nWorkingDirectory=/opt/flatrun\nExecStart=/usr/local/bin/flatrun-agent --config /opt/flatrun/config.yml\nRestart=always\nRestartSec=10\nStandardOutput=journal\nStandardError=journal\n\n[Install]\nWantedBy=multi-user.target\n```\n\n3. Enable and start the service:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable flatrun-agent\nsudo systemctl start flatrun-agent\n\n# Check status\nsudo systemctl status flatrun-agent\n\n# View logs\nsudo journalctl -u flatrun-agent -f\n```\n\n## Directory Structure\n\n```\n/etc/flatrun/                    # FlatRun configuration (example location)\n└── config.yml                   # Agent configuration\n\n/usr/local/bin/\n└── flatrun-agent                # Agent binary\n\n/path/to/deployments/            # Configurable via deployments_path\n├── .flatrun/                    # FlatRun metadata\n│   └── templates/               # Quick App templates\n├── myapp/                       # Example deployment\n│   └── docker-compose.yml\n└── nginx/                       # Nginx reverse proxy\n    └── conf.d/\n```\n\nThe deployments directory can be located anywhere on your system (e.g., `/home/user/deployments`, `/srv/deployments`, `/var/lib/flatrun/deployments`). Configure it via `deployments_path` in your config file.\n\n## API Endpoints\n\n### Authentication\n- `POST /api/auth/login` - Login with API key\n- `GET /api/auth/validate` - Validate JWT token\n- `GET /api/auth/status` - Check auth status\n\n### Deployments\n- `GET /api/deployments` - List all deployments\n- `POST /api/deployments` - Create new deployment\n- `GET /api/deployments/:name` - Get deployment details\n- `DELETE /api/deployments/:name` - Delete deployment\n- `POST /api/deployments/:name/start` - Start deployment\n- `POST /api/deployments/:name/stop` - Stop deployment\n- `POST /api/deployments/:name/restart` - Restart deployment\n- `GET /api/deployments/:name/logs` - Get deployment logs\n\n### Docker Resources\n- `GET /api/containers` - List containers\n- `GET /api/images` - List images\n- `GET /api/volumes` - List volumes\n- `GET /api/networks` - List networks\n- `POST /api/networks` - Create network\n- `DELETE /api/networks/:name` - Delete network\n\n### Other\n- `GET /api/health` - Health check\n- `GET /api/stats` - System statistics\n- `GET /api/certificates` - List SSL certificates\n- `GET /api/templates` - List Quick App templates\n- `GET /api/plugins` - List installed plugins\n\n## Security Considerations\n\n- Always use strong, unique API keys\n- Generate a secure JWT secret (use `openssl rand -base64 32`)\n- Run behind a reverse proxy (nginx) with HTTPS in production\n- Restrict Docker socket access appropriately\n- Keep the agent updated\n\n## Development\n\n```bash\n# Run tests\nmake test\n\n# Clean build artifacts\nmake clean\n\n# Run in development mode with hot reload (requires air)\nair\n```\n\n## Troubleshooting\n\n### Agent won't start\n- Check Docker is running: `systemctl status docker`\n- Verify Docker socket permissions: `ls -la /var/run/docker.sock`\n- Check config file syntax: validate your YAML\n\n### Authentication issues\n- Ensure API key matches between UI and agent config\n- Verify JWT secret is set\n- Check CORS origins include your UI URL\n\n### Can't see deployments\n- Verify `deployments_path` exists and is readable\n- Check each deployment has a valid `docker-compose.yml`\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatrun%2Fagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatrun%2Fagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatrun%2Fagent/lists"}