{"id":49549130,"url":"https://github.com/quidow/gridfleet","last_synced_at":"2026-06-04T21:00:50.344Z","repository":{"id":354789947,"uuid":"1224740597","full_name":"quidow/gridfleet","owner":"quidow","description":"Appium + Selenium Grid control plane for device test labs","archived":false,"fork":false,"pushed_at":"2026-06-02T13:18:28.000Z","size":9364,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T15:14:15.787Z","etag":null,"topics":["appium","device-farm","device-manager","selenium-grid"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quidow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-29T15:23:22.000Z","updated_at":"2026-06-02T13:16:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/quidow/gridfleet","commit_stats":null,"previous_names":["quidow/gridfleet"],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/quidow/gridfleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quidow%2Fgridfleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quidow%2Fgridfleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quidow%2Fgridfleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quidow%2Fgridfleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quidow","download_url":"https://codeload.github.com/quidow/gridfleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quidow%2Fgridfleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33917202,"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-04T02:00:06.755Z","response_time":64,"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":["appium","device-farm","device-manager","selenium-grid"],"created_at":"2026-05-02T21:04:30.074Z","updated_at":"2026-06-04T21:00:50.338Z","avatar_url":"https://github.com/quidow.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GridFleet\n\n[![CI](https://github.com/quidow/gridfleet/actions/workflows/ci.yml/badge.svg)](https://github.com/quidow/gridfleet/actions/workflows/ci.yml)\n[![Security](https://github.com/quidow/gridfleet/actions/workflows/security.yml/badge.svg)](https://github.com/quidow/gridfleet/actions/workflows/security.yml)\n\nGridFleet is an Appium + Selenium Grid control plane for device labs and CI\nfleets. It gives operators one place to register hosts, discover devices, start\nAppium nodes, route Selenium Grid sessions, reserve capacity for test runs, and\ninspect fleet health.\n\nDriver-specific behavior lives in driver packs. The core manager owns Appium\nprocess lifecycle, Selenium Grid relay registration, scheduling, reservations,\nhealth monitoring, and the dashboard; packs provide discovery rules, platform\nmetadata, readiness fields, lifecycle actions, capability defaults, and optional\nadapter code.\n\n![GridFleet dashboard demo](docs/assets/gridfleet-dashboard.png)\n\n## What You Get\n\n- FastAPI backend with PostgreSQL, async SQLAlchemy, Alembic migrations, and\n  leader-owned background workers.\n- Host agent that runs on each device host and manages discovery, Appium\n  processes, Selenium Grid relay nodes, tools, and telemetry.\n- React operator dashboard for devices, hosts, sessions, runs, analytics,\n  driver packs, settings, notifications, and bulk operations.\n- Python testkit for pytest/Appium suites that need run registration,\n  reservations, platform selection, and Grid connection helpers.\n- Curated Appium driver-pack manifests and adapter source for Android,\n  Apple/XCUITest, and Roku lanes.\n\n## Repository Layout\n\n```text\ngridfleet/\n├── backend/       FastAPI manager API, services, models, migrations, tests\n├── agent/         Host-side FastAPI agent and native install/update scripts\n├── frontend/      React + TypeScript operator console\n├── driver-packs/  Curated manifests and adapter source\n├── testkit/       Supported Python pytest/Appium helper package\n├── docker/        Development and production compose files\n├── docs/          Guides, references, and runbooks\n└── scripts/       Backup/restore, agent install, and driver-pack helpers\n```\n\n## Quick Start\n\nThe fastest local trial is the Docker stack:\n\n```bash\ncd docker\ndocker compose up --build -d\n```\n\nLocal endpoints:\n\n- Dashboard: `http://localhost:3000`\n- Backend API: `http://localhost:8000`\n- Selenium Grid: `http://localhost:4444`\n\nTo stop the stack:\n\n```bash\ncd docker\ndocker compose down\n```\n\n## Driver Pack Tarballs\n\nGridFleet does not check in generated `.tar.gz` driver-pack artifacts. Build\nthem locally when you want uploadable packs for another GridFleet instance or\nfor exercising the upload path.\n\nBuild all curated packs:\n\n```bash\npython3 scripts/build_driver_tarballs.py\nls dist/driver-packs\n```\n\nThe script reads manifests from `driver-packs/curated/`, builds matching\nadapter wheels from `driver-packs/adapters/`, and writes deterministic tarballs\nto `dist/driver-packs/`.\n\nBuild one custom or curated pack:\n\n```bash\npython3 scripts/build_driver_pack_tarball.py \\\n  --pack-dir driver-packs/curated/appium-roku-dlenroc \\\n  --out /tmp/appium-roku-dlenroc-upload.tar.gz \\\n  --id uploaded/appium-roku-dlenroc \\\n  --release 2026.04.0-upload\n```\n\nIf the pack needs custom adapter code, add `--adapter-dir path/to/adapter`.\nAdapter builds require `uv` on `PATH`; uploaded adapter wheels execute on agent\nhosts, so only upload code you trust.\n\nRead the full upload guide in\n[docs/guides/driver-pack-tarball-upload.md](docs/guides/driver-pack-tarball-upload.md).\n\n## Production Compose\n\nFor a production-style manager deployment:\n\n```bash\ncd docker\ncp .env.example .env\ndocker compose --env-file .env -f docker-compose.prod.yml up --build -d\n```\n\nBefore using production compose, edit `docker/.env` and replace all placeholder\npasswords and session secrets. Deployment, backup, restore, and rollback notes\nare in [docs/guides/deployment.md](docs/guides/deployment.md).\n\n## Development Setup\n\nPrerequisites:\n\n- Python 3.12+\n- `uv`\n- Node.js 24\n- Docker with `docker compose`\n- PostgreSQL 18 for backend tests, or the Docker Postgres service\n\nBackend:\n\n```bash\ncd backend\nuv sync --extra dev\nuv run alembic upgrade head\nuv run uvicorn app.main:app --reload\n```\n\nAgent:\n\n```bash\ncd agent\nuv sync --extra dev\nuv run uvicorn agent_app.main:app --reload --port 5100\n```\n\nFrontend:\n\n```bash\ncd frontend\nnpm ci\nnpm run dev\n```\n\nHost agents can be bootstrapped from the published Python package:\n\n```bash\nVERSION=0.3.0 bash scripts/install-agent.sh --manager-url http://MANAGER_IP:8000\n```\n\n## Validation\n\nRun the fastest relevant checks for the area you changed:\n\n```bash\ncd backend \u0026\u0026 uv run ruff check app/ tests/ \u0026\u0026 uv run mypy app/ \u0026\u0026 uv run pytest -q -n auto\ncd agent \u0026\u0026 uv run ruff check agent_app/ tests/ \u0026\u0026 uv run mypy agent_app/ \u0026\u0026 uv run pytest -q\ncd testkit \u0026\u0026 uv run --extra dev pytest -q\ncd frontend \u0026\u0026 npm run lint \u0026\u0026 npm run build \u0026\u0026 npm run test:e2e:mocked\n```\n\nFrontend live E2E requires backend, Postgres, and the frontend dev server:\n\n```bash\ncd frontend\nnpm run test:e2e:live\n```\n\n## Documentation\n\n- [Docs index](docs/README.md)\n- [Architecture reference](docs/reference/architecture.md)\n- [Environment reference](docs/reference/environment.md)\n- [Settings reference](docs/reference/settings.md)\n- [Capabilities reference](docs/reference/capabilities.md)\n- [Device intake and discovery](docs/guides/device-intake-and-discovery.md)\n- [Host onboarding](docs/guides/host-onboarding.md)\n- [CI integration](docs/guides/ci-integration.md)\n- [Testkit reference](docs/reference/testkit.md)\n- [Release policy](docs/reference/release-policy.md)\n\n## Security\n\nGridFleet controls Appium nodes, host agents, driver-pack execution, and optional\nhost terminals. Treat deployments as trusted lab or CI infrastructure, not as\npublic internet services.\n\nStart with [SECURITY.md](SECURITY.md) and\n[docs/guides/security.md](docs/guides/security.md). Do not expose backend,\nagent, Selenium Grid, or host-terminal ports directly to the public internet.\n\n## Project Status\n\nGridFleet is in an initial public preview. The system is usable for lab and CI\nexperiments, but pre-1.0 API, deployment, driver-pack, and testkit contracts may\nchange across minor releases. Real-device smoke coverage remains a local/manual\nrelease gate.\n\n## Community And License\n\n- License: [Apache License 2.0](LICENSE)\n- Changelog: [CHANGELOG.md](CHANGELOG.md)\n- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)\n- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- Security policy: [SECURITY.md](SECURITY.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquidow%2Fgridfleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquidow%2Fgridfleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquidow%2Fgridfleet/lists"}