README

The bridge between PHP and AWS Lambda Web Functions.

Run Laravel and PHP on AWS Lambda Web Functions.

Arco is an open-source PHP CLI by Multiapi. It builds your app, uploads it and deploys it to Lambda Web Functions with FrankenPHP, with environments, secrets, custom domains and rollback built in.

Status: 0.9, the API freeze before 1.0. Lambda Web Functions launched in October 2026 and Arco is new. It already runs a production Laravel app. 0.9 is the last release allowed to break arco.php, the CLI or the --json output; from 1.0 they stay compatible until 2.0 (what is covered). Upgrading from an earlier version: read Upgrading.

Requirements

• PHP >= 8.3 and Composer on your machine (no Docker, no Node.js needed locally)
• An AWS account and a profile for it (SSO, assume-role and static-key profiles all work)
• For Laravel: Laravel >= 11 with laravel/octane

Quick start

composer require multiapi/arco-laravel laravel/octane
composer require --dev multiapi/arco
vendor/bin/arco init
vendor/bin/arco secret:set app-key --env=production
vendor/bin/arco deploy --env=production

init asks for the app name, region, environments and (optionally) a custom domain, and writes arco.php. The first deploy asks which AWS profile to use and remembers it in .arco/local.php.

What you get

• One command deploys. arco deploy builds a copy of the project, packages it with a pinned, attestation-verified FrankenPHP arm64 binary, uploads it, creates a revision, shifts traffic, checks the health route and rolls back if it fails.
• Laravel with Octane workers on FrankenPHP. Node.js only launches FrankenPHP at start-up; it is not in the request path.
• Environments (production, staging, …), each its own Web Function, all in one arco.php.
• Secrets as arco-ssm: / arco-secret: references, resolved when the function starts and scoped in IAM to exactly what you reference.
• Operations. arco logs inspects the deployed app from your terminal. With the opt-in console function (->console()), arco command and arco tinker run on it and migrations can run on every deploy before traffic moves; ->scheduler(N) runs Laravel's scheduler on a UTC clock-aligned EventBridge rule.
• Queues. ->queue('emails') creates an SQS queue with a dead-letter queue and a worker function that runs the jobs with Laravel's own worker (retries, failed() and failed_jobs as usual); ->onQueue('emails') works without app changes.
• Storage, cache and failed jobs. ->storage('uploads') creates a private S3 bucket that is a Laravel disk (the first one is the default disk, unless every one says default: false), with optional public prefixes, expiry rules and CORS; ->cache() and ->failedJobsTable() create DynamoDB tables for Laravel's cache and failed jobs, and ->table('state') one (PK/SK) for your own code, named in ARCO_TABLES. Each can point at one you already have (existing:), and removed ones stay in AWS with their data.
• Custom domains in one line: certificate, CloudFront and DNS records, with the DNS zone in the same AWS account, another account, Cloudflare, or outside AWS.

Configuring arco.php

arco init writes this file; edit it by hand or with arco set / arco domain:add. It is plain PHP returning an App:

<?php

use Multiapi\Arco\Config\App;
use Multiapi\Arco\Config\Environment;
use Multiapi\Arco\Config\Runtime;

return App::make('shop')                       // function name: shop-<environment>
    ->region('us-east-1')
    ->runtime(fn (Runtime $r) => $r->php('8.5'))   // PHP minor; an Arco upgrade never changes it

    // App level: defaults for every environment
    ->timeout(28)
    ->variables(['APP_LOCALE' => 'es'])
    ->exclude(['docs/**'])                       // never packaged

    ->environment('production', fn (Environment $env) => $env
        ->profile('my-company-prod')             // AWS profile used to deploy this environment
        ->domain(['shop.example.com', 'api.shop.example.com'])
        ->dns('my-company-dns')                  // Route 53 zone lives in another account (optional)
        ->maxInstances(10)                       // cap on running instances (and DB connections)
        ->variables([
            'APP_ENV' => 'production',
            'APP_KEY' => 'arco-ssm:/shop/production/app-key',            // SSM parameter
            'DB_PASSWORD' => 'arco-secret:shop/production/db#password',  // Secrets Manager JSON key
        ])
        ->permissions([                          // extra IAM for the function (S3, SES, …)
            ['Effect' => 'Allow', 'Action' => 's3:GetObject', 'Resource' => 'arn:aws:s3:::shop-files/*'],
        ])
        ->runtime(fn (Runtime $r) => $r->phpIni(['memory_limit' => '512M'])))

    ->environment('staging', fn (Environment $env) => $env
        ->variables(['APP_ENV' => 'staging', 'APP_KEY' => 'arco-ssm:/shop/staging/app-key']));

Inheritance: a value set on an environment wins over the app level, which wins over Arco's default. variables() and permissions() are merged (environment entries added to the app's). arco info --env=production shows every resolved value and where it came from.

The main options:

Every option, the packaging rules and the Laravel preset are in the configuration reference.

Commands

Messages are in English or Spanish (--lang=es or ARCO_LANG=es).

Documentation

• Getting started
• Configuration reference
• Upgrading: every breaking change per version, and what 1.x keeps stable
• Try it locally with Floci

Limits (of Lambda Web Functions)

• 2 vCPU and 2 GB per instance, 512 MB unzipped package, 512 MB /tmp, arm64 only
• Regions: us-east-1, us-east-2, us-west-2, ap-northeast-1, eu-west-1
• The console function (commands, tinker, scheduler) is opt-in and a classic Lambda function: 250 MB unzipped package, with a static PHP CLI instead of the FrankenPHP binary
• The queue workers are classic Lambda functions running the console package (250 MB unzipped), one per queue; a batch of jobs runs for at most the worker's timeout (up to 900 s)
• Arco deploys HTTP functions, an optional console function for commands and the scheduler, SQS queue workers, S3 buckets and DynamoDB tables for the cache and failed jobs, in one region per app

Packages

The packages are published from one monorepo. Please open issues in multi-api/arco.

License

MIT