README

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

• PHP ^8.2 | ^8.3 | ^8.4
• Laravel ^11 | ^12 (illuminate/*)
• spatie/laravel-backup ^10 (backup engine, used from PA3)

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

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

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)

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)

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

composer install
composer test

The suite pins against the frozen Hub Agent Contract fixtures in tests/Fixtures/hub-contract/ (no live Hub required).

License

MIT. See LICENSE.