# Run a Laravel dev stack

Run Laravel, Vite, and a queue worker as separate commands in Solo. Each command has its own output and status in the sidebar. Coding agents can inspect those commands through Solo MCP.

Use an existing Laravel application with PHP, Node, dependencies, and `.env` configured. For the worker, you need an asynchronous queue connection. With `QUEUE_CONNECTION=sync`, Laravel runs jobs during the request and does not send them to a worker. See [Laravel queue connections](https://laravel.com/docs/12.x/queues#connections-vs-queues).

## Add the commands

If Herd, Docker, or another tool already runs a service, use that process and omit its command below.

Save this `solo.yml` in the project root. If the file already exists, add the missing commands to its `processes` mapping.

```yaml
name: Storefront
processes:
  Laravel:
    command: php artisan serve --host=127.0.0.1 --port=8000
    auto_start: false
  Vite:
    command: npm run dev
    auto_start: false
  Queue:
    command: php artisan queue:work
    auto_start: false
    auto_restart: true
```

Keep credentials in `.env` or your environment. See the [solo.yml reference](../projects/solo-yml.md) for the supported fields.

## Start and check each service

Load the project in Solo, then review and trust the imported commands. For an existing project, accept the configuration sync prompt.

1. Start **Laravel** and open the URL printed in its output.
2. Start **Vite** and check that the application's frontend loads.
3. Start **Queue** and inspect its output for connection errors.

The worker needs the same environment and queue connection as the application that dispatches jobs. If a command fails, inspect its output before starting another copy.

## Restart after a job file changes

A file-watch restart can interrupt the current job. Use it only for development jobs you can interrupt. To let jobs finish first, use the graceful restart procedure below.

Add the watch pattern to **Queue** in `solo.yml`:

```yaml
processes:
  Queue:
    command: php artisan queue:work
    auto_start: false
    auto_restart: true
    restart_when_changed:
      - app/Jobs/**/*.php
```

If your jobs live elsewhere, change the pattern to match their directory.

1. Accept the configuration sync prompt.
2. Restart **Queue** to activate the pattern.
3. Add a comment to an existing PHP job under `app/Jobs` and save it.
4. Check the Queue output for the restart.
5. Remove your test comment without reverting other edits.

See [File-watch auto-restart](../commands/file-watch-auto-restart.md) for pattern rules.

## Restart after the current job

Omit `restart_when_changed` when workers need to finish their current jobs before restarting. From a terminal with the same application and cache configuration as the worker, run:

```bash
php artisan queue:restart
```

Laravel sends a restart signal through the application's cache. The worker finishes its current job and exits. With `auto_restart: true`, Solo starts the command again. See [Laravel worker restarts](https://laravel.com/docs/12.x/queues#queue-workers-and-deployment).

Clicking **Stop** in Solo keeps the command stopped. If the worker repeatedly exits, inspect its output. Solo pauses automatic restarts after too many attempts.

## Let an agent inspect the commands

[Launch an agent](../agents/launching-agents.md) in this project and connect it to [Solo MCP](../integrations/mcp-server.md). Send this prompt:

```text
Use Solo MCP to inspect Laravel, Vite, and Queue in this project.
Report their status, recent errors, and detected ports.
Do not start or restart processes, or edit files.
```

Launch agents through the agent picker. Command restart settings do not apply to agent sessions.

To use one agent for edits and another for review, see [Run Claude Code and Codex together](./agents-spawning-agents.md).

---

Are you a human? Read this doc on the web: https://soloterm.com/docs/workflows/laravel-dev-stack