> For the complete documentation index, see [llms.txt](https://vibemx.gitbook.io/neuronai-studio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vibemx.gitbook.io/neuronai-studio/getting-started/installation.md).

# Installation

This guide walks through installing NeuronAI Studio in a Laravel application, from Composer dependencies to opening the dashboard.

## Prerequisites

* PHP 8.2 or higher
* Laravel 11, 12, or 13
* A database configured in your `.env`
* API credentials for at least one LLM provider (configured via Neuron AI)

## Step 1 — Install packages

```bash
composer require digitalelvis/neuronai-studio neuron-core/neuron-ai
```

NeuronAI Studio depends on [neuron-core/neuron-ai](https://docs.neuron-ai.dev/overview/getting-started). Provider credentials live in `config/neuron.php` (published by the installer) — the studio does not duplicate API key configuration.

## Step 2 — Install NeuronAI Studio

```bash
php artisan neuronai-studio:install
```

This publishes `config/neuron.php` and `config/neuronai-studio.php`, migrations, and assets. Set provider credentials in `.env` (for example `OPENAI_KEY`).

The install command also performs the following:

| Step            | Publish tag                  | Description                                                    |
| --------------- | ---------------------------- | -------------------------------------------------------------- |
| Provider config | `neuron-config`              | Publishes `config/neuron.php` (API keys / providers)           |
| Config          | `neuronai-studio-config`     | Publishes `config/neuronai-studio.php`                         |
| Migrations      | `neuronai-studio-migrations` | Copies migration files (also auto-loaded from package)         |
| Assets          | `neuronai-studio-assets`     | Publishes pre-built JS/CSS to `public/vendor/neuronai-studio/` |
| Views           | `neuronai-studio-views`      | Only with `--with-views` flag                                  |

The installer prompts to run migrations. Confirm unless you prefer to migrate manually.

### Install options

```bash
# Overwrite existing published config/migrations
php artisan neuronai-studio:install --force

# Publish Blade views for customization
php artisan neuronai-studio:install --with-views
```

## Step 3 — Publish assets (if needed)

The install command publishes assets automatically. Re-run manually after package updates or when rebuilding frontend bundles:

```bash
php artisan vendor:publish --tag=neuronai-studio-assets --force
```

## Step 4 — Open the dashboard

Visit `/{route_prefix}` — default:

```
http://localhost:8000/neuronai-studio
```

Configure the prefix with `NEURONAI_STUDIO_ROUTE_PREFIX` in `.env`.

## Optional — Locale / language

Studio UI follows the host app locale (`APP_LOCALE`). Ship catalogs for `en` (default) and `pt_BR`. Override with:

```env
NEURONAI_STUDIO_LOCALE=pt_BR
```

Or publish and customize translations:

```bash
php artisan vendor:publish --tag=neuronai-studio-lang
```

## Optional — External observability

Studio Debugger traces are on by default. To also export to Inspector or Langfuse:

```bash
php artisan neuronai-studio:install-observability inspector
php artisan neuronai-studio:install-observability langfuse
```

See [Native tracing](/neuronai-studio/observability/native-tracing.md), [Inspector](/neuronai-studio/observability/inspector.md), and [Langfuse](/neuronai-studio/observability/langfuse.md).

> **Screenshot pending:** Dashboard after successful installation.
>
> Asset path: `docs/assets/screenshots/install-success-dashboard.png` Capture: `/neuronai-studio` immediately after install — dark theme, 1440×900

## Environment variables

| Variable                               | Default             | Description                                   |
| -------------------------------------- | ------------------- | --------------------------------------------- |
| `NEURONAI_STUDIO_ROUTE_PREFIX`         | `neuronai-studio`   | URL prefix for all studio routes              |
| `NEURONAI_STUDIO_TABLE_PREFIX`         | `neuronai_studio_`  | Database table prefix                         |
| `NEURONAI_STUDIO_DEFAULT_PROVIDER`     | `openai`            | Default provider in agent forms               |
| `NEURONAI_STUDIO_DEFAULT_MODEL`        | `gpt-4o-mini`       | Default model in agent forms                  |
| `NEURONAI_STUDIO_EXPORT_NAMESPACE`     | `App\Neuron`        | Namespace for exported PHP classes            |
| `NEURONAI_STUDIO_EXPORT_PATH`          | `app/Neuron`        | Directory for exported files                  |
| `NEURONAI_STUDIO_ASYNC_RUNS_ENABLED`   | `false`             | Run workflows in background via queue jobs    |
| `NEURONAI_STUDIO_QUEUE`                | `default`           | Queue name for workflow jobs                  |
| `NEURONAI_STUDIO_QUEUE_CONNECTION`     | —                   | Optional queue connection override            |
| `NEURONAI_STUDIO_QUEUE_TRIES`          | `1`                 | Max job attempts                              |
| `NEURONAI_STUDIO_QUEUE_BACKOFF`        | `30`                | Retry delay in seconds                        |
| `NEURONAI_STUDIO_ALLOW_BUILDER_TOOLS`  | `APP_ENV === local` | Allow PHP Class Builder create/edit in Studio |
| `NEURONAI_STUDIO_USAGE_EXPORT_ENABLED` | `true`              | Host metering API (`GET …/usage`)             |
| `NEURONAI_STUDIO_USAGE_EVENTS_ENABLED` | `false`             | Dispatch `RunUsageRecorded` on terminal runs  |

See [Configuration](/neuronai-studio/reference/configuration.md) for the full list. Auth for the usage export API is host-owned — set `usage.export.middleware` (e.g. `auth:sanctum`). See [Usage Export API](/neuronai-studio/analytics/export-api.md).

### Async workflow runs (optional)

The Studio test harness and agent playground stream over a long-lived HTTP+SSE connection. Under PHP-FPM / Nginx that can hit `max_execution_time` or proxy idle timeouts (**504**) on loops, MCP stdio, or multi-LLM graphs. For production workflow execution, prefer the queue path instead of relying on sync streams.

To execute workflows outside the synchronous test harness SSE path, enable async runs and start a queue worker:

```env
NEURONAI_STUDIO_ASYNC_RUNS_ENABLED=true
NEURONAI_STUDIO_QUEUE=default
```

```bash
php artisan queue:work --queue=default
```

Poll trace status at `GET /neuronai-studio/traces/{id}/json`, or stream live progress at `GET /neuronai-studio/workflows/runs/{run}/events/stream`. Details: [Runtime & Traces](/neuronai-studio/workflows/runtime-and-traces.md#queue-runner) and [Long-running runs under PHP-FPM](/neuronai-studio/workflows/runtime-and-traces.md#long-running-runs-under-php-fpm).

## Publish tags reference

| Tag                          | Destination                               |
| ---------------------------- | ----------------------------------------- |
| `neuron-config`              | `config/neuron.php`                       |
| `neuronai-studio-config`     | `config/neuronai-studio.php`              |
| `neuronai-studio-migrations` | `database/migrations/`                    |
| `neuronai-studio-views`      | `resources/views/vendor/neuronai-studio/` |
| `neuronai-studio-assets`     | `public/vendor/neuronai-studio/`          |

Details: [Publish Tags](/neuronai-studio/reference/publish-tags.md).

## Authorization

In the `local` environment, the studio gate allows all access. In other environments, authenticated users are required by default.

Define a custom gate in `AppServiceProvider`:

```php
use Illuminate\Support\Facades\Gate;

Gate::define('viewNeuronAIStudio', function ($user) {
    return $user->isAdmin();
});
```

See [Security & Access](/neuronai-studio/workflows/security-and-access.md).

## Troubleshooting

### UI looks outdated after a package update

If you previously published Blade views, your app may load stale templates instead of the package defaults:

```bash
rm -rf resources/views/vendor/neuronai-studio
php artisan view:clear
php artisan vendor:publish --tag=neuronai-studio-assets --force
```

### Rebuilding frontend assets (package development)

When editing `resources/js/` in the package source:

```bash
npm install
npm run build
php artisan vendor:publish --tag=neuronai-studio-assets --force
```

See [Frontend Bundles](/neuronai-studio/reference/frontend-bundles.md).

### Migrations fail

Ensure your database connection is configured and run:

```bash
php artisan migrate
```

Migrations are also loaded automatically from the package — you do not need to publish them unless you want to modify them.

## Optional — AI-assisted development

NeuronAI Studio ships an [Agent Skill](https://agentskills.io/) for Cursor, Claude Code, and similar tools:

```
vendor/digitalelvis/neuronai-studio/skills/neuronai-studio/
```

Install or point your assistant at that directory so it follows Studio conventions and links into the package docs. Full instructions: [AI-Assisted Development](/neuronai-studio/getting-started/ai-assisted-development.md).

## Next steps

* [Quickstart: First Agent](/neuronai-studio/getting-started/quickstart-first-agent.md) — create and test an agent in five minutes
* [Quickstart: First Workflow](/neuronai-studio/getting-started/quickstart-first-workflow.md) — run a workflow from a template
* [Demo App](/neuronai-studio/getting-started/demo-app.md) — local development with the bundled example app
* [AI-Assisted Development](/neuronai-studio/getting-started/ai-assisted-development.md) — use Studio skills with Cursor / Claude


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vibemx.gitbook.io/neuronai-studio/getting-started/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.