PHPackages sidewalkdevelopers/platform-agent - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. sidewalkdevelopers/platform-agent ActiveLibrary[File & Storage](/categories/file-storage) sidewalkdevelopers/platform-agent ================================= Official Sidewalk Developers Group Platform Agent — near-zero-code backup, checksum, upload, heartbeat and restore integration for the Distributed Backup Orchestration Platform (Cloud Hub). v1.0.0(today)00MITPHPPHP ^8.2 || ^8.3 || ^8.4 Since Jun 30Pushed todayCompare [ Source](https://github.com/Sidewalk-Developer-Group/platform-agent)[ Packagist](https://packagist.org/packages/sidewalkdevelopers/platform-agent)[ Docs](https://github.com/Sidewalk-Developer-Group/platform-agent)[ RSS](/packages/sidewalkdevelopers-platform-agent/feed)WikiDiscussions master Synced today READMEChangelog (4)Dependencies (7)Versions (2)Used By (0) Platform Agent ============== [](#platform-agent) [![CI](https://github.com/Sidewalk-Developer-Group/platform-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/Sidewalk-Developer-Group/platform-agent/actions/workflows/ci.yml)[![Latest Version](https://camo.githubusercontent.com/c9818a099e2990313f76bcf97a6ebbcb3f8bf113ae14512b19a7284960c411e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7369646577616c6b646576656c6f706572732f706c6174666f726d2d6167656e742e737667)](https://packagist.org/packages/sidewalkdevelopers/platform-agent)[![License](https://camo.githubusercontent.com/de96086bcfe1430fe0cb272021ebe8571bef35021d6c5060d230624804f919b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7369646577616c6b646576656c6f706572732f706c6174666f726d2d6167656e742e737667)](LICENSE) The official **Sidewalk Developers Group Platform Agent** — the near-zero-code integration package that connects a customer Laravel application to the **Distributed Backup Orchestration Platform** (the Cloud Hub). It is installed into a *customer's* Laravel app and ships **all** integration logic so the customer writes near-zero code: backup creation (database + files, split), SHA256 checksum generation, resumable archive upload, heartbeats, health and version reporting, and agent-pull restore. > Status: **1.0.0 — full PA0–PA5 track shipped** (first public Packagist release). Onboarding (`install`/`diagnose`), `register`/`heartbeat`/`report`, the `PlatformAgent::schedule()` wiring, split backup → checksum → resumable upload + run-log, agent-PULL `restore`, and the optional Reverb/Pusher restore-discovery push `listen` are all live. Minimum Hub Agent Contract: **v1.2.0**. See `CHANGELOG.md` and ADR-0007 §11a / BUILD\_PLAN §11a. Requirements ------------ [](#requirements) - PHP `^8.2 | ^8.3 | ^8.4` - Laravel `^11 | ^12` (`illuminate/*`) - `spatie/laravel-backup ^10` (backup engine, used from PA3) Installation ------------ [](#installation) ``` composer require sidewalkdevelopers/platform-agent php artisan platform-agent:install ``` `platform-agent:install` (PA1) publishes the config, performs the one-time **enrollment → runtime token exchange**, persists the durable runtime token **encrypted in your application's database**, wires the schedule, and runs a connectivity/auth pre-flight. Configuration — the only three env vars --------------------------------------- [](#configuration--the-only-three-env-vars) ``` PLATFORM_URL= # Cloud Hub base URL (host only; /api/v1 is appended) PLATFORM_TOKEN= # one-time ENROLLMENT token (ability agent:register only) PLATFORM_APPLICATION_UUID= # the bound Application UUID (sanity/match check) ``` **Token model (ADR-0007 Addendum D — enrollment-exchange):** `PLATFORM_TOKEN` is a short-lived, single-use **enrollment** token an operator mints for you. On `install` it is exchanged for a durable **runtime** token (abilities `app:backup` + `app:heartbeat` + `app:restore`) that is stored **encrypted in your database — never written back to `.env`**. After enrollment the `.env` enrollment token is spent and can be discarded. The agent never sends `application_id` in a request body — identity is the token's bound Application. Everything else (HTTP timeouts/retries, per-kind backup cadence/retention, the single-POST-vs-tus `threshold_bytes`) is config-driven in `config/platform-agent.php` — nothing about endpoints, thresholds or schedules is hardcoded. Commands -------- [](#commands) CommandPurposePhase`platform-agent:install`Onboard (publish config, enroll, persist runtime token, wire schedule)PA1`platform-agent:diagnose`Print resolved config (token redacted) + connectivity/version statusPA1`platform-agent:register`Register / re-pair (version + host/fingerprint)PA2`platform-agent:heartbeat`Frequent liveness ping (bytes only — Rule 1)PA2`platform-agent:report`Richer health/version/environment reportPA2`platform-agent:backup --kind=database|files`Split backup → checksum → uploadPA3`platform-agent:restore {location}`Agent-PULL restore: pull → verify SHA256 (Rule 4) → deposit `backup.zip` + sidecar at {location} (non-destructive; `--job=` to pick among many)PA4`platform-agent:listen {location?}`Subscribe to Hub restore broadcasts and drain approved jobs instantly; poll fallback always on (`--once` = single poll sweep)PA5Scheduling ---------- [](#scheduling) Wire the agent's recurring work with a single line in `routes/console.php`: ``` use Illuminate\Console\Scheduling\Schedule; use SidewalkDevelopers\PlatformAgent\PlatformAgent; PlatformAgent::schedule(app(Schedule::class)); ``` It registers the heartbeat (every 5 min — Rule 2), an hourly report, and both split backups (`--kind=database` / `--kind=files`) on their configured cadences (`config/platform-agent.php` → `backup.kinds.*.cadence`). Backup execution lands at PA3; the schedule entries are wired now so onboarding stays near-zero-code. Restore-discovery push (optional, latency follow-up) ---------------------------------------------------- [](#restore-discovery-push-optional-latency-follow-up) By default the agent **polls** for approved restore jobs (Rule 6). For lower latency, `platform-agent:listen` keeps a long-lived **Reverb/Pusher** subscription to the Hub's per-Application **private** restore channel and drains a restore the instant the Hub broadcasts. **Polling is never removed** — `:listen` runs a poll sweep on startup, on every idle tick, and on any disconnect, and the scheduled `:listen --once` fallback stays wired regardless. ``` PLATFORM_RESTORE_LOCATION=/var/backups/restore # deposit dir (also enables the scheduled poll) PLATFORM_RESTORE_PUSH_ENABLED=true # opt in to the live push daemon PLATFORM_RESTORE_PUSH_KEY= # Hub broadcaster (Reverb/Pusher) app key PLATFORM_RESTORE_PUSH_HOST= # defaults to the Hub host PLATFORM_RESTORE_PUSH_PORT=443 ``` Run the daemon under a process supervisor (systemd / supervisor): ``` php artisan platform-agent:listen ``` The push only changes **when** a restore runs; the authoritative action is always the same manifest → pull → SHA256 verify (Rule 4) → non-destructive deposit → report path as the poll command. Channel subscription is authorized by the runtime PAT via `POST /api/v1/agent/broadcasting/auth`; the Hub binds the channel to the token's Application (the channel id is never trusted from the client). The transport is dependency-free (native PHP streams, RFC 6455) — no WebSocket library is added to your app. Dev-environment upload limits (setup note) ------------------------------------------ [](#dev-environment-upload-limits-setup-note) Large archives upload via the **tus.io 1.0 resumable protocol** to `POST /api/v1/agent/uploads` (small archives use single-POST `/api/v1/agent/archives`). The Laravel-layer cap is ~10 GiB; the real ceilings are **infrastructure**. For large uploads ensure: PHP `upload_max_filesize`, `post_max_size`, `memory_limit`, `max_execution_time`; nginx `client_max_body_size` and `proxy_request_buffering off` (and/or `fastcgi_request_buffering off`) for streaming `PATCH`; php-fpm timeouts. The tus protocol headers and `Authorization` must survive CORS/proxy middleware. Testing ------- [](#testing) ``` composer install composer test ``` The suite pins against the **frozen Hub Agent Contract** fixtures in `tests/Fixtures/hub-contract/` (no live Hub required). License ------- [](#license) MIT. See `LICENSE`. ### Health Score 41 — FairBetter than 87% of packages Maintenance100 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 0d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/aff5390b2ef05535565e59d071198938114f2340a8575ffad32006c661a7be1e?d=identicon)[jackwander](/maintainers/jackwander) --- Top Contributors [![jackwander](https://avatars.githubusercontent.com/u/32908963?v=4)](https://github.com/jackwander "jackwander (6 commits)") --- Tags laravelbackupAgentdisaster-recoverysidewalk-developersplatform-agent ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/sidewalkdevelopers-platform-agent/health.svg) ``` [![Health](https://phpackages.com/badges/sidewalkdevelopers-platform-agent/health.svg)](https://phpackages.com/packages/sidewalkdevelopers-platform-agent) ``` ### Alternatives [larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k51.0M7.8k](/packages/larastan-larastan)[spatie/laravel-responsecache Speed up a Laravel application by caching the entire response 2.8k8.7M64](/packages/spatie-laravel-responsecache)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 77018.2M127](/packages/laravel-mcp)[psalm/plugin-laravel Psalm plugin for Laravel 3345.1M337](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 1.0k2.1M169](/packages/laravel-ai)[spatie/laravel-export Create a static site bundle from a Laravel app 672139.5k6](/packages/spatie-laravel-export) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)