Installation

Introduction

The Quickstart gets you to a working terminal loop in five minutes. This page is the full install reference: every prerequisite, what the wizard actually does behind the scenes, and how to invoke each step on its own.

If you're just kicking the tires, the Quickstart is plenty. If you're putting Laraclaw into a real project — and especially if you're heading toward Deployment — read on.

Prerequisites

Laraclaw requires:

• PHP 8.4 or higher — we lean on the latest type system goodies.
• Laravel 12 or higher — older majors won't resolve.
• Redis — used by the confirmation flow (the agent asking yes/no through chat) and by default for the queue.
• A queue worker (php artisan queue:work) — almost every connector dispatches the agent run to a job.
• The Laravel scheduler (schedule:work or a cron entry) — reminders and heartbeats fire from scheduled commands.

PostgreSQL with the pgvector extension is optional. You'll want it if you plan to use memory at any meaningful scale — without it, Laraclaw stores embeddings as JSON and computes cosine similarity in PHP. Fine for a few thousand chunks; slow past that.

!TIP Don't have Redis locally? brew install redis && brew services start redis on macOS, or docker run -p 6379:6379 redis if you'd rather containerize it.

How to Install

Install via Composer:

composer require laraclaw/laraclaw

Then publish the config and migrations:

php artisan vendor:publish --tag=laraclaw

This puts the following on disk:

• config/laraclaw.php — all the configuration knobs.
• database/migrations/*_create_laraclaw_* — the five tables (Introduction covers what each one stores).
• laraclaw/instructions.md — the base system prompt. Edit this to change the agent's default behavior.
• laraclaw/personas/default.md — a starter persona, applied automatically. Edit it, or delete it to run on the base prompt alone.
• laraclaw/skills/greeting/SKILL.md — a tiny example skill to copy from.

Those last three make up the agent folder: everything that shapes how the agent thinks, in plain Markdown you can review in a pull request.

!TIP Publishing never overwrites a file that already exists, so you can re-run vendor:publish --tag=laraclaw after an upgrade without losing your edits. To pull in a fresh copy of a file you have edited, delete it first.

The Setup Wizard

Run the interactive wizard:

php artisan laraclaw:setup

Here's what it does, in order:

1. Runs migrations — creates the five laraclaw_* tables.
2. Picks the owner user (LARACLAW_ADMIN_USER_ID) and registers their first account row.
3. Picks the AI provider via AI_DEFAULT, prompting for the API key.
4. Lets you select connectors to set up (Telegram, Slack, Email), then runs the per-connector wizard for each.
5. Optionally enables the API connector and prints a Bearer token you can use right away.
6. Asks whether to enable memory, the File Manager, Calendar, Read Database, and Headless Browser tools, and the Tinker tool.

Each step writes to your .env file. You can re-run the wizard at any time, and any answer you've already given is the new default — handy when you just want to update one thing.

Running Sub-Commands Directly

Don't want the full wizard? Each step has its own command:

php artisan laraclaw:setup-admin              # owner user + first account
php artisan laraclaw:setup-agent              # AI provider + key
php artisan laraclaw:setup-connector telegram # one connector at a time
php artisan laraclaw:setup-connector slack
php artisan laraclaw:setup-connector email
php artisan laraclaw:setup-connector api
php artisan laraclaw:setup-calendar           # Google or Apple
php artisan laraclaw:setup-files              # File Manager allowlist
php artisan laraclaw:setup-memory             # memory + embedding provider
php artisan laraclaw:setup-read-database      # read-only DB connection
php artisan laraclaw:setup-browser            # headless browser (Lightpanda)

These are the same building blocks laraclaw:setup calls. Run any of them whenever you need to change just that piece.

Verifying the Installation

Start the supporting processes:

php artisan queue:work
php artisan schedule:work

Then open a terminal session with the agent:

php artisan laraclaw:chat

Type a message. The agent should reply.

If it doesn't, the most common culprits are:

• No queue worker running. Most connectors (terminal included) queue the agent run.
• Wrong AI_DEFAULT value or missing API key. Re-run php artisan laraclaw:setup-agent.
• LARACLAW_ADMIN_USER_ID doesn't match a real user. Re-run php artisan laraclaw:setup-admin.

What's Next

From here, head to Connectors to register a webhook URL with whichever channel you've enabled, or Customization to tune behaviour.

Until next time!