README

The receive side of Matte — self-hosted, unmetered image background removal on Laravel Cloud. This package turns a slim Laravel app into a single-tenant background-removal API: it authenticates requests, stores the image, runs the bg-remover binary on a queue worker, and returns a transparent PNG.

Read-only mirror. This repository is a read-only split of the artisan-build/matte monorepo. Issues and pull requests are disabled here — please open them on the monorepo.

Why it's built for Laravel Cloud

matte-server is deliberately shaped around one validated fact: the bg-remover binary runs directly on a Laravel Cloud managed-queue worker — no container, no sidecar, no system packages. That is the whole reason Matte can be "fork it and deploy it," with nothing to operate but a normal Laravel Cloud app.

• arm64, self-contained. Cloud workers are arm64 (Graviton) on Debian 12. The pinned bg-remover-linux-arm64 release statically links OpenCV; only libonnxruntime.so.1 is co-located and resolved via the binary's $ORIGIN RUNPATH.
• Baked into the artifact. matte:provision-binary runs as a build command, so the arch-correct binary lands in the deploy artifact and ships to every web and worker instance (build-command filesystem changes persist; deploy-command changes do not).
• BinaryLocator resolves the right binary per platform (macOS arm64 for local dev, Linux arm64/x86_64 on servers), so the same code runs everywhere.
• php artisan matte:doctor runs a real conversion on the host and reports binary presence, $ORIGIN resolution, and a passing GrabCut — run it on a Cloud instance to prove the worker is healthy.

The full pipeline lives inside one managed app: ingest → object storage → managed queue → worker runs the binary → transparent PNG → status/webhook. Object storage and the database are Cloud-managed resources; nothing else is required.

The HTTP API

All routes are token-authenticated with a Bearer token (resolved against MATTE_TOKENS).

Options (form fields on submit): mode (grabcut | ml), preset (fast | balanced | quality), model, edge_mode (blur | bilateral | guided), iterations, margin, plus optional idempotency_key and callback_url.

Completion webhook. If a callback_url is supplied and MATTE_WEBHOOK_SECRET is set, the worker POSTs {job_id, status, output_ref, error} with an X-Matte-Signature: sha256=<hmac> header (HMAC-SHA256 over the exact body) so the receiver can verify authenticity.

Console commands

Configuration

Env vars (all MATTE_* keys live in config/matte-server.php):

Installation

You don't usually install this directly — it's the package the Matte app requires. To stand a server up, fork artisan-build/matte and use the bundled provisioning-matte-on-cloud skill (or its manual reference/).

License

MIT. See LICENSE.