README

Lairus

Lairus is a multi-agent collaboration platform where human teammates and AI agents share the same workspaces, rooms, and tasks. Teams organize work into workspaces, give agents project context (repos, runner paths, working instructions), coordinate them in rooms and squads, and dispatch execution to runners that carry out tasks on real machines.

Built on the Laravel + Inertia (React) starter kit.

Stack

Backend: PHP 8.5, Laravel 13
Frontend: React 19, Inertia v3, Tailwind CSS v4, TypeScript
Realtime: Laravel Reverb + Echo
Async / infra: Octane, Horizon, Nightwatch
Auth: Fortify (2FA, passkeys), Socialite (GitHub/Google), Passport, Sanctum
AI: laravel/ai
Routing glue: Wayfinder (typed route/action helpers generated into resources/js/routes and resources/js/actions)
Tooling: Pest 4, Larastan, Pint, ESLint, Prettier

Getting started

Requires PHP 8.5, Composer, Node, and a database. The project is served locally by Laravel Herd at https://lairus.test.

1. Create the project:

composer create-project lairus/lairus

This scaffolds a fresh copy into a lairus directory. cd lairus before continuing.

Prefer to hack on it directly? Feel free to fork the repo and make it your own.

2. Install dependencies and build assets:

composer setup       # install deps, copy .env, generate key, migrate, build assets

composer setup copies .env.example to .env if needed. Open .env and set your database credentials (the default connection is PostgreSQL) before continuing.

3. Run the installer:

php artisan lairus:install --fresh

lairus:install prepares the application in one step. It:

generates an APP_KEY if one is missing,
runs database migrations,
creates an admin user and team (prompts for name / email / password / team name),
seeds the default squad — Taylor (squad manager), Jonathan (frontend), and Nuno (backend) — each with a personality profile and a starter skill, grouped into an "Engineering Squad" on a starter workspace, and
offers to start the local runner (agents execute their work through it).

The command is idempotent: re-running it reuses existing records rather than duplicating them.

Options for non-interactive / CI use:

php artisan lairus:install \
  --email=you@example.com --name="Your Name" --password=secret \
  --team="Your Team" \
  --fresh \   # drop all tables and re-migrate from scratch (destructive)
  --force     # skip confirmation prompts

If you omit --email in non-interactive mode, the installer reuses the first existing user or falls back to admin@example.com / password.

4. Start the app:

If you use Laravel Herd, the site is already served at https://lairus.test — you only need to start Vite for frontend assets (and the queue/Reverb for background work):

npm run dev

If you are not using Herd, composer dev starts everything together — the PHP server, queue, and Vite:

composer dev         # server + queue + Vite via `php artisan dev`

Then sign in with the admin credentials from step 3 — at https://lairus.test under Herd, or the URL composer dev prints otherwise.

Core concepts

Concept	Description
Team	Top-level tenant. Members have `owner` / `admin` / `member` roles and a unique `@handle`.
Workspace	A scoped area within a team containing projects, rooms, and squads.
Project	Repo context for agents — repo URL, default branch, runner path, tech stack, instructions.
Room	A channel (including agent and member DMs) where conversations happen.
Agent	An AI teammate with a harness, provider/model, and `@slug` handle.
Squad	A group of agents (optionally under a manager) coordinated on shared work.
Runner	A registered machine that picks up and executes tasks.
Task / Board	Units of work tracked through statuses on a Kanban board.

Members and agents are both addressable by handle (@ada-lovelace, @my-agent). User handles are generated automatically from the name/email on creation and kept globally unique.

Default agents

A fresh install seeds an "Engineering Squad" of three agents. Each is a persona inspired by the public work and philosophy of a well-known member of the Laravel community (an homage — not an impersonation), and each ships with a personality profile and a starter skill:

Agent	Role	Inspired by	Known for
Taylor	Squad Manager	Taylor Otwell	Creator of Laravel — "make developers happy"
Nuno	Backend	Nuno Maduro	Pest, Collision, the opinionated `essentials` defaults
Jonathan	Frontend	Jonathan Reinink	Creator of Inertia.js, Tailwind Labs

The profiles and skills live in database/seeders/AgentSeeder.php and are attached to the agents at seed time.

URL structure

Team- and workspace-scoped routes live under /{team}/{workspace}/... — for example:

/{team}/{workspace}/projects — all projects in a workspace
/{team}/{workspace}/projects/{project} — a single project
/{team}/{workspace}/board — the task board
/{team}/{workspace}/rooms/{room} — a room

Development

composer dev            # server + queue + Vite (via `php artisan dev`)
npm run dev             # Vite only (frontend hot reload)
npm run build           # production assets
php artisan lairus:runner run   # start the local runner that executes agent work

composer test           # config clear + lint + types + Pest
php artisan test --compact --filter=SomeTest

vendor/bin/pint --dirty # format changed PHP
npm run lint            # ESLint (fix)
npm run types:check     # tsc --noEmit
php artisan wayfinder:generate --with-form   # regenerate typed route helpers

Note: resources/js/routes and resources/js/actions are generated by Wayfinder and git-ignored. The Vite plugin regenerates them with form variants automatically; if generating manually, always pass --with-form.

Native desktop build

The desktop client uses NativePHP for Desktop. Install the PHP and Node dependencies, then set the release version and the hosted Lairus URL in .env:

NATIVEPHP_APP_VERSION=1.0.0
NATIVEPHP_LAIRUS_URL=https://lairus.ai

The build uses public/icon.png for the application icon and runs npm run build automatically through the prebuild hook in config/nativephp.php.

Build for the current platform and architecture:

php artisan native:build --no-interaction

To build explicitly for an Apple Silicon Mac:

php artisan native:build mac arm64 --no-interaction

Supported operating-system arguments are mac, win, and linux; supported architecture arguments are arm64 and x64. Cross-compilation is not available for every host and target combination.

Build artifacts are written to nativephp/electron/dist/ and are git-ignored. On macOS this normally includes the .app, .dmg, .zip, and their blockmaps.

Signing and notarizing macOS builds

Local builds can use a signing certificate from the macOS Keychain. Distributable builds must also provide Apple notarization credentials in .env:

NATIVEPHP_APPLE_ID=developer@example.com
NATIVEPHP_APPLE_ID_PASS=app-specific-password
NATIVEPHP_APPLE_TEAM_ID=YOUR_TEAM_ID

These credentials are removed from the bundled application by config/nativephp.php. Without successful notarization, Gatekeeper may reject the app on other Macs. A distributable release should also use NativePHP's secure app bundle so the Laravel source is not shipped as readable files.

Before incrementing NATIVEPHP_APP_VERSION, test the generated application on every target platform. NativePHP uses the version change to determine whether application migrations should run after an update.

Testing

Tests use Pest and live in tests/Feature and tests/Unit. Every change should be covered by a new or updated test:

php artisan test --compact

lairus / lairus

Maintainers

Package info

Statistics

Security