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.
Harness	The reasoning/execution layer that turns a task into audited, verified work.
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.

The Lairus harness

The Lairus harness is the execution layer that sits between a task and an AI/provider CLI. A normal provider CLI can generate text; the harness is responsible for turning that into work that is scoped, observable, reusable, and safe enough to trust.

At a high level:

User / task / squad plan
  → RunnerJob
    → runner daemon claims the job
      → app-scoped memory + approved skills are retrieved
        → provider CLI or Lairus reasoning pipeline executes
          → verification / gate / revision loop
            → run events, token usage, memory updates, skill candidates
              → final answer or blocked/held result

Execution modes

Mode	When it runs	What it does
Provider CLI	Agent uses `codex`, `claude`, `gemini`, `cursor`, `hermes`, `opencode`, `pi`, or `openclaw`	Runs the selected local CLI with runner safety policy, streamed logs, scoped memory, and approved skills.
Lairus full pipeline	Harness is `lairus` and a model provider is available	Runs the full reasoning pipeline: intake → plan → work → verify → compose → gate.
Lairus gate-over-CLI	Harness is `lairus` but generation falls back to an installed CLI	Wraps the request in Lairus work framing, generates with a provider CLI, then gates/revises the candidate before emitting.
Shell	Explicit shell job	Runs allowlisted shell commands with dangerous-command blocking and timeout controls.

The full Lairus pipeline is intentionally not just "ask an LLM." It separates generation from permission to emit. Candidate answers have to survive verification and gating before they become a user-visible result.

Memory and skills

Harness runs can use two memory surfaces:

Application memory — workspace/project scoped memories stored in Laravel and retrieved through authenticated runner endpoints.
Local runner memory — optional SQLite + FTS5 memory under .lairus/memory/lairus.db, configured in runner/lairus.toml.

Approved app skills and promoted local skills are materialized for the provider CLI before execution. New skill candidates can be drafted after successful runs, but they stay inactive/draft until a human promotes them. That keeps the system self-improving without silently changing future behavior.

Useful local curation commands:

lairus-runner memory search "runner tests"
lairus-runner skills list
lairus-runner skills list --status draft
lairus-runner skills promote learned-runner-workflow

Traces, usage, and auditability

Every complex run emits structured RunEvent records back to the Laravel app. The Trace page shows important harness events such as memory retrieval, skill retrieval, Lairus stages, gates, revisions, and errors. Usage & cost is tracked from run metadata and completion payloads.

When local persistent tracing is enabled in runner/lairus.toml, Lairus also writes JSONL event logs to:

.lairus/runs/<run-id>/events.jsonl

Replay a local harness audit with:

lairus-runner harness-audit <run-id>

Safety model

The runner keeps execution scoped and reversible by default:

runner jobs are team-scoped and authenticated with runner tokens,
working directories are checked against runner allowed paths,
dangerous shell commands are blocked,
provider CLIs run with the safest supported headless/sandbox flags,
custom provider CLI args are rejected,
skills learned from a run are draft/inactive until promotion,
memory is injected as context, not as instructions,
high-stakes Lairus pipeline outputs can be held for human review.

The goal is a teammate that learns over time, but still leaves a clear audit trail for what it used, what it decided, and what it changed.

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

Try Lairus

Lairus is built around a simple belief: AI agents should not live in a separate chat box from the work. They should share the same rooms, tasks, projects, memories, approvals, and audit trail as the rest of the team.

Install it, run the local runner, and try giving an agent a real task in a real workspace. For more information, examples, and updates, visit lairus.ai.

Lairus is open-sourced software licensed under the MIT license.

lairus / lairus

Maintainers

Package info

Statistics

Security