PHPackages artisan-build/matte-server - 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. [Utility & Helpers](/categories/utility) 4. / 5. artisan-build/matte-server ActiveLibrary[Utility & Helpers](/categories/utility) artisan-build/matte-server ========================== The server-side Matte package consumed by the Matte app. v2.1.0(1mo ago)02MITPHPPHP ^8.3 Since Jun 14Pushed 1mo agoCompare [ Source](https://github.com/artisan-build/matte-server)[ Packagist](https://packagist.org/packages/artisan-build/matte-server)[ RSS](/packages/artisan-build-matte-server/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (13)Versions (5)Used By (0) matte-server ============ [](#matte-server) The **receive side** of [Matte](https://github.com/artisan-build/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`](https://github.com/artisan-build/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`](https://github.com/artisan-build/matte) monorepo. Issues and pull requests are disabled here — please open them on the monorepo. Why it's built for Laravel Cloud -------------------------------- [](#why-its-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 ------------ [](#the-http-api) All routes are token-authenticated with a `Bearer` token, resolved against the hashed `api_tokens`table (managed by [`artisan-build/built-for-cloud`](https://github.com/artisan-build/built-for-cloud)) or the `FALLBACK_TOKEN` environment variable. Method & pathPurpose`POST /v1/remove`Submit an image (multipart `image` + options). Returns `202 {job_id, status:"queued"}`. With `?sync=1`, runs inline and returns `200 image/png`.`GET /v1/jobs/{id}`Job status: `queued` / `processing` / `done` / `failed`, plus `output_ref` / `error`.`GET /v1/jobs/{id}/result`Streams the transparent PNG (`200 image/png`); `409` if not done yet.**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=`header (HMAC-SHA256 over the exact body) so the receiver can verify authenticity. Console commands ---------------- [](#console-commands) CommandWhat it does`matte:provision-binary`Fetch the pinned `bg-remover` binary + ONNX runtime (+ optional model) into the runtime layout. Run as a **build command**.`matte:doctor`Verify the binary runtime and run a real conversion.`matte:remove `Synchronous CLI conversion (no queue) — the local eyeball loop.API tokens are managed by the `token:*` commands from [`artisan-build/built-for-cloud`](https://github.com/artisan-build/built-for-cloud)(`token:create`, `token:rotate`, `token:revoke`, `token:list`, `token:usage`). Configuration ------------- [](#configuration) Env vars (all `MATTE_*` keys live in `config/matte-server.php`): KeyMeaning`FALLBACK_TOKEN`Optional single bootstrap/fallback API token (plaintext). Delete it and use per-app `api_tokens` for production workloads.`MATTE_DISK`Storage disk for originals + outputs. Defaults to `FILESYSTEM_DISK` (the bucket Cloud injects), then `local`.`MATTE_RUNTIME_PATH`Where the binary is provisioned. On Cloud, a `base_path` location so it ships in the artifact.`MATTE_BG_REMOVER_TAG`Pinned `bg-remover` release (default `v0.7.1`).`MATTE_QUEUE_CONNECTION`Queue for the removal job. Leave unset to use the app default (the managed queue).`MATTE_WEBHOOK_SECRET`HMAC secret for signing completion webhooks.`MATTE_DEFAULT_MODE`, `MATTE_TIMEOUT`, `MATTE_MODEL_NAME`, `MATTE_MODEL_URL`, `MATTE_ROUTE_PREFIX`Defaults / tuning.Installation ------------ [](#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`](https://github.com/artisan-build/matte) and use the bundled `provisioning-matte-on-cloud` skill (or its manual `reference/`). License ------- [](#license) MIT. See [LICENSE](LICENSE). ### Health Score 40 — FairBetter than 86% of packages Maintenance91 Actively maintained with recent releases Popularity3 Limited adoption so far Community8 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 93.3% 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 Every ~0 days Total 4 Last Release 44d ago Major Versions v0.1.0 → v1.0.02026-06-14 v1.0.0 → v2.0.02026-06-15 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/1053395?v=4)[Ed Grosvenor](/maintainers/edgrosvenor)[@edgrosvenor](https://github.com/edgrosvenor) --- Top Contributors [![edgrosvenor](https://avatars.githubusercontent.com/u/1053395?v=4)](https://github.com/edgrosvenor "edgrosvenor (14 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") --- Tags laravelmcpmatte ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/artisan-build-matte-server/health.svg) ``` [![Health](https://phpackages.com/badges/artisan-build-matte-server/health.svg)](https://phpackages.com/packages/artisan-build-matte-server) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M348](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 77922.3M189](/packages/laravel-mcp)[laravel/ai The official AI SDK for Laravel. 1.0k3.2M251](/packages/laravel-ai)[moonshine/moonshine Laravel administration panel 1.3k253.1k86](/packages/moonshine-moonshine)[api-platform/laravel API Platform support for Laravel 58174.6k17](/packages/api-platform-laravel)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.4k](/packages/tomshaw-electricgrid) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)