To install the LaraOwl server manually using Composer, ensure you have PHP 8.3+, Node.js 18+, MySQL 8.0+ or PostgreSQL, and a queue worker installed.

1. Create the project: composer create-project laraowl/laraowl laraowl.
2. Install frontend dependencies: npm install.
3. Setup environment: cp .env.example .env and php artisan key:generate.
4. Run migrations: php artisan migrate (after configuring your database in .env).
5. Build assets: npm run build.
6. Start the server: php artisan serve.

composer create-project laraowl/laraowl laraowl
cd laraowl
npm install
cp .env.example .env
php artisan key:generate
# (Configure .env database settings)
php artisan migrate
npm run build
php artisan serve

To deploy the LaraOwl server using Docker, use the provided Dockerfile and docker-compose.yml.

1. Copy the production environment file: cp .env.prod .env.
2. Update the following variables in your .env file with your production domain and Laravel Reverb credentials:
   • APP_URL
   • APP_HOSTNAME
   • REVERB_APP_ID
   • REVERB_APP_KEY
   • REVERB_APP_SECRET
3. Start the server in production mode using docker compose up -d --build.

Ensure your DNS resolves for both your-production-domain.com and ws.your-production-domain.com. Caddy handles SSL automatically.

# Copy production env
cp .env.prod .env

# Start production server
docker compose up -d --build

To monitor a Laravel application, install the client package and configure it to point to your LaraOwl server.

1. Install the package: composer require laraowl/client.
2. Run the interactive setup: php artisan laraowl:install.

Alternatively, manually configure your .env file:

• LARAOWL_SERVER_URL: The URL of your LaraOwl server.
• LARAOWL_TOKEN: The project API token found in Project Settings → API Keys.

To forward application logs to LaraOwl, add laraowl to your LOG_STACK in .env: LOG_STACK=stack,laraowl.

composer require laraowl/client
php artisan laraowl:install

Manual .env configuration

LARAOWL_SERVER_URL=https://your-laraowl-server.com LARAOWL_TOKEN=your_project_api_token LOG_STACK=stack,laraowl

If you installed LaraOwl via Docker and need to create an initial admin user, access the application container via bash and use php artisan tinker to run the following command:

App\Models\User::updateOrCreate(
    ['email' => 'admin@laraowl.com'],
    ['name' => 'Admin', 'password' => bcrypt('changeme')]
);

docker compose exec -ti app /bin/bash

# Inside the container:
php artisan tinker

# Inside tinker:
App\Models\User::updateOrCreate(
    ['email' => 'admin@laraowl.com'],
    ['name' => 'Admin', 'password' => bcrypt('changeme')]
);

When deploying LaraOwl in a production environment, ensure the following key variables are configured in your .env file. For optimal performance, use redis for the QUEUE_CONNECTION and reverb for the BROADCAST_CONNECTION.

APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=laraowl
DB_USERNAME=laraowl
DB_PASSWORD=your-secure-password

# Queue (use Redis for best performance)
QUEUE_CONNECTION=redis

# Broadcasting
BROADCAST_CONNECTION=reverb

# Reverb WebSocket
REVERB_HOST="your-domain.com"
REVERB_PORT=8080
REVERB_SCHEME=https

LaraOwl requires the Laravel scheduler to be running to handle uptime checks (every 30 seconds) and daily data pruning based on your retention settings. Add the following entry to your server's crontab:

Replace /path/to/laraowl with your application's directory.

* * * * * cd /path/to/laraowl && php artisan schedule:run >> /dev/null 2>&1

LaraOwl supports the Model Context Protocol (MCP), allowing AI coding agents to query telemetry, list projects, and manage issues.

1. Generate an MCP token via the dashboard (Settings → MCP Tokens) or via Artisan: php artisan laraowl:mcp-token user@example.com --name=mcp.
2. Add the server to your agent (e.g., Claude Code): claude mcp add --transport http laraowl https://your-laraowl-server.com/mcp --header "Authorization: Bearer <token>".

Available Tools:

• list-projects
• list-issues
• get-issue
• query-telemetry
• update-issue-status
• comment-on-issue

# Generate token
php artisan laraowl:mcp-token user@example.com --name=mcp

# Add to Claude Code
claude mcp add --transport http laraowl https://your-laraowl-server.com/mcp \
  --header "Authorization: Bearer <token>"

To ensure high availability in production, use Supervisor to manage the LaraOwl queue worker and the Reverb WebSocket server.

Note: Replace /path/to/laraowl/ with the actual absolute path to your Laravel installation.

[program:laraowl-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/laraowl/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/laraowl/queue.log

[program:laraowl-reverb]
command=php /path/to/laraowl/artisan reverb:start
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/laraowl/reverb.log

If the laraowl:update command returns an error stating that update checks are disabled, you must enable them by setting the following environment variable in your .env file:

LARAOWL_UPDATE_CHECK=true

LaraOwl can be deployed as a multi-container stack using Docker Compose. The setup includes the main application, background workers (Horizon and Schedule), real-time communication (Reverb), a web server (Caddy), a PostgreSQL database, and a Redis instance.

Configuration is primarily driven by a .env file which provides credentials and versioning information. The stack relies on several named volumes for data persistence, including db-data, redis-data, storage, public, caddy_data, and caddy_config.

docker-compose up -d

The Docker Compose setup uses an .env file to populate critical configuration values. Ensure the following variables are defined in your .env file to match the service requirements:

• APP_VERSION: Sets the version of the LaraOwl image to use (defaults to latest).
• DB_DATABASE: The name of the PostgreSQL database.
• DB_USERNAME: The PostgreSQL user.
• DB_PASSWORD: The PostgreSQL password.
• REDIS_PASSWORD: The password for the Redis instance.