> 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/reference/configuration.md). # Configuration Complete reference for `config/neuronai-studio.php`. Publish with: ```bash php artisan vendor:publish --tag=neuronai-studio-config ``` ## Routing & auth | Key | Env | Default | Description | | -------------- | ------------------------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `route_prefix` | `NEURONAI_STUDIO_ROUTE_PREFIX` | `neuronai-studio` | URL prefix for all studio routes | | `table_prefix` | `NEURONAI_STUDIO_TABLE_PREFIX` | `neuronai_studio_` | Prefix applied to **all** package tables (definitions, MCP, RAG, runs/traces, evals). See [Database schema](/neuronai-studio/reference/database-schema.md). | | `middleware` | — | `['web', 'neuronai-studio.auth']` | Route middleware stack | | `gate` | — | `viewNeuronAIStudio` | Authorization gate name | ## Export | Key | Env | Default | Description | | ------------------ | ---------------------------------- | ------------ | ---------------------------------- | | `export_namespace` | `NEURONAI_STUDIO_EXPORT_NAMESPACE` | `App\Neuron` | PHP namespace for exported classes | | `export_path` | `NEURONAI_STUDIO_EXPORT_PATH` | `app/Neuron` | Export directory | ## CodeGen feature flags Master + children. Defaults are `true` only when `APP_ENV=local`. Effective capabilities: * `canExport` = `codegen.enabled && codegen.export` * `canPreview` = `codegen.enabled && codegen.preview` Master off turns both children off even if their env vars are `true`. Runtime resolution of already-exported classes is **not** gated. | Key | Env | Default | Description | | ----------------- | --------------------------------- | ------------------- | -------------------------------------------------------------------- | | `codegen.enabled` | `NEURONAI_STUDIO_CODEGEN_ENABLED` | `APP_ENV === local` | Master gate (make-tool, import to Studio, prerequisite for children) | | `codegen.export` | `NEURONAI_STUDIO_CODEGEN_EXPORT` | `APP_ENV === local` | Disk writes + CLI export + Export UI | | `codegen.preview` | `NEURONAI_STUDIO_CODEGEN_PREVIEW` | `APP_ENV === local` | Code panel / generated preview (no disk write) | ```env NEURONAI_STUDIO_CODEGEN_ENABLED=true NEURONAI_STUDIO_CODEGEN_EXPORT=false NEURONAI_STUDIO_CODEGEN_PREVIEW=true ``` ## AI providers | Key | Env | Default | Description | | ------------------ | ---------------------------------- | --------------------------------- | ----------------------------- | | `providers` | — | openai, anthropic, gemini, ollama | Provider/model picker options | | `default_provider` | `NEURONAI_STUDIO_DEFAULT_PROVIDER` | `openai` | Default provider in forms | | `default_model` | `NEURONAI_STUDIO_DEFAULT_MODEL` | `gpt-4o-mini` | Default model in forms | Credentials are **not** stored here — they come from `config/neuron.php`. ## Usage & cost estimation Approximate prices for `estimated_cost` on LLM spans and runs. Values are **estimates, not provider invoices**. Rates are per **1k tokens** in the install currency. | Key | Env | Default | Description | | --------------------------- | -------------------------------------- | ----------------- | --------------------------------------------------------------------------- | | `usage.currency` | `NEURONAI_STUDIO_USAGE_CURRENCY` | `USD` | Single currency for all estimates | | `usage.pricing` | — | catalog model map | `provider` → `model` → `{ prompt_per_1k, completion_per_1k }` | | `usage.export.enabled` | `NEURONAI_STUDIO_USAGE_EXPORT_ENABLED` | `true` | Register host metering routes (`routes/usage.php`) | | `usage.export.route_prefix` | `NEURONAI_STUDIO_USAGE_EXPORT_PREFIX` | `null` | Override prefix; `null` → `stream_adapters.route_prefix` | | `usage.export.middleware` | — | `null` | Override middleware; `null` → `stream_adapters.middleware` (host owns auth) | | `usage.events.enabled` | `NEURONAI_STUDIO_USAGE_EVENTS_ENABLED` | `false` | Dispatch `RunUsageRecorded` on terminal runs | Lookup is exact-match on the span's `provider` + `model`. Missing keys → cost `0`. Ollama catalog entries default to `0`. Override after publishing config: ```php 'usage' => [ 'currency' => 'USD', 'pricing' => [ 'openai' => [ 'gpt-4o-mini' => [ 'prompt_per_1k' => 0.00015, 'completion_per_1k' => 0.0006, ], ], ], ], ``` See [Cost estimation](/neuronai-studio/analytics/costs.md) and [Usage Export API](https://github.com/digitalelvis/neuronai-studio/tree/main/docs/guides/analytics/export-api.md). ## Chat history | Key | Env | Default | Description | | ----------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `chat_history_context_window` | `NEURONAI_STUDIO_CHAT_HISTORY_CONTEXT_WINDOW` | `150000` | Global default max tokens for agent threads when `memory_config.context_window` is unset | ## Memory / summarization Per-agent settings live in `AgentDefinition.memory_config` (Studio form + node overrides). Optional dedicated summarizer: | Key | Env | Default | Description | | ---------------------------- | ------------------------------------- | ------- | ------------------------------------------------------------------- | | `memory.summarizer.provider` | `NEURONAI_STUDIO_SUMMARIZER_PROVIDER` | `null` | Provider for history compaction; falls back to the agent's provider | | `memory.summarizer.model` | `NEURONAI_STUDIO_SUMMARIZER_MODEL` | `null` | Model for history compaction; falls back to the agent's model | When summarization is enabled and history exceeds the window, Studio persists a summary message and keeps durable rows (no silent deletes). On summarizer failure, Studio falls back to non-destructive trim (exclude from prompt, keep rows). ### Prompt assembly budgets (`memory_config`) Optional integer keys (min 1). Unset = disabled (byte-identical pass-through): | Key | Description | | --------------------- | ------------------------------------------------------ | | `budget_rag` | Cap interpolated RAG context (`rag_context`) | | `budget_tool_results` | Cap tool results in the agent tool loop / chat history | | `budget_state` | Cap each non-RAG interpolated state field | Per-node overrides use the same flat keys on agent-node `data`. Token estimates align with Neuron `TokenCounter` (\~4 characters per token). ## Queue | Key | Env | Default | Description | | -------------------- | ------------------------------------ | --------- | ---------------------------------------------------------------------------------- | | `async_runs_enabled` | `NEURONAI_STUDIO_ASYNC_RUNS_ENABLED` | `false` | Enable async workflow runs via queue jobs (SSE harness remains default when false) | | `queue` | `NEURONAI_STUDIO_QUEUE` | `default` | Queue name for `RunWorkflowJob` and `ResumeWorkflowJob` | | `queue_connection` | `NEURONAI_STUDIO_QUEUE_CONNECTION` | `null` | Queue connection override | | `queue_tries` | `NEURONAI_STUDIO_QUEUE_TRIES` | `1` | Max attempts for workflow queue jobs | | `queue_backoff` | `NEURONAI_STUDIO_QUEUE_BACKOFF` | `30` | Seconds before retry after failure | ## Async progress | Key | Env | Default | Description | | ------------------------ | ---------------------------------------- | ------- | ------------------------------------------------------ | | `async_progress.enabled` | `NEURONAI_STUDIO_ASYNC_PROGRESS_ENABLED` | `true` | Jobs emit step events into a cache buffer for SSE tail | | `async_progress.ttl` | `NEURONAI_STUDIO_ASYNC_PROGRESS_TTL` | `3600` | Buffer TTL (seconds); use Redis in multi-server setups | | `async_progress.poll_ms` | `NEURONAI_STUDIO_ASYNC_PROGRESS_POLL_MS` | `200` | SSE tail poll interval | Studio SSE: `GET /{prefix}/workflows/runs/{run}/events/stream` (auth Studio). Echo / `ShouldBroadcast` is not required. ## Parallel (interpreted) | Key | Env | Default | Description | | ---------------------- | -------------------------------------- | ------------ | ----------------------------------------- | | `parallel.concurrency` | `NEURONAI_STUDIO_PARALLEL_CONCURRENCY` | `concurrent` | `concurrent` (Amp fibers) or `sequential` | ## Observability Env-first monitoring layers. Native Debugger is separate from external exporters. | Key | Env | Default | Description | | ----------------------------------- | ------------------------------------------- | ------- | --------------------------------------------------------- | | `observability.native_tracing` | `NEURONAI_STUDIO_NATIVE_TRACING` | `true` | Persist Studio Debugger spans via `TelemetryTracker` | | `observability.inspector.enabled` | `NEURONAI_STUDIO_INSPECTOR_ENABLED` | `true` | Attach Inspector when `INSPECTOR_INGESTION_KEY` is set | | `observability.langfuse.enabled` | `NEURONAI_STUDIO_LANGFUSE_ENABLED` | `true` | Attach Langfuse when keys + package present | | `observability.langfuse.public_key` | `LANGFUSE_PUBLIC_KEY` | — | Langfuse public key | | `observability.langfuse.secret_key` | `LANGFUSE_SECRET_KEY` | — | Langfuse secret key | | `observability.langfuse.base_url` | `LANGFUSE_BASE_URL` (`LANGFUSE_HOST` alias) | — | Langfuse API base URL | | `observability.metadata` / `tags` | — | `[]` | Optional metadata/tags for exporters | | `inspector_enabled` | `NEURONAI_STUDIO_INSPECTOR_ENABLED` | `true` | **Deprecated** alias of `observability.inspector.enabled` | See [Native tracing](https://github.com/digitalelvis/neuronai-studio/tree/main/docs/guides/observability/native-tracing.md), [Inspector](https://github.com/digitalelvis/neuronai-studio/tree/main/docs/guides/observability/inspector.md), [Langfuse](https://github.com/digitalelvis/neuronai-studio/tree/main/docs/guides/observability/langfuse.md). ```bash php artisan neuronai-studio:install-observability inspector php artisan neuronai-studio:install-observability langfuse ``` ## Tools | Key | Env | Default | Description | | --------------------- | ------------------------------------- | -------------------- | --------------------------------------------------------- | | `allow_builder_tools` | `NEURONAI_STUDIO_ALLOW_BUILDER_TOOLS` | `APP_ENV === local` | Allow create/edit of PHP Class Builder tools in Studio UI | | `tools` | — | calculator, calendar | Built-in toolkit registry | | `tool_scan_paths` | — | `app/Neuron/Tools` | Paths to scan for PHP Tool classes | When `allow_builder_tools` is `false`, the builder tab is hidden and Livewire rejects builder saves. Runtime still resolves already-exported tools that have `config.class_path`. See [Builder Tools](/neuronai-studio/tools/builder-tools.md) and [Security & Access](/neuronai-studio/workflows/security-and-access.md#builder-tools). ## Structured output | Key | Default | Description | | ------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------- | | `structured_output_scan_paths` | `{export_path}/Output` when directory exists, else `[]` | Paths to scan for PHP output classes with `SchemaProperty` attributes | Classes discovered here populate the **Output class** dropdown on Agent and LLM nodes in the workflow canvas. Each path can be absolute or relative to the application base path. Default behavior: ```php 'structured_output_scan_paths' => is_dir($exportPath.'/Output') ? [$exportPath.'/Output'] : [], ``` Add extra scan paths when output classes live outside the export directory: ```php 'structured_output_scan_paths' => [ app_path('Neuron/Output'), app_path('DTOs/AgentOutput'), ], ``` Classes must have public properties annotated with `NeuronAI\StructuredOutput\SchemaProperty`. Abstract classes and classes without schema properties are ignored. ## Workflows | Key | Default | Description | | --------------------- | ------------------------------------ | ----------------------------- | | `workflow_scan_paths` | `app/Neuron`, `app/Neuron/Workflows` | PHP workflow class scan paths | | `workflow_json_paths` | `workflows/` | JSON workflow import paths | ### Loop defaults | Key | Env | Default | Description | | ------------------------ | --- | ------- | ---------------------------------------------------- | | `loop.default_max_steps` | — | `10` | Default `max_steps` when a Loop node omits the field | | `loop.global_max_steps` | — | `1000` | Hard cap on total node executions per run | ### Checkpoints Opt-in per-node result cache used to skip re-executing expensive nodes on resume (set `data.checkpoint: true` on Agent/LLM/RAG/Tool nodes). See [Node checkpoints](/neuronai-studio/workflows/runtime-and-traces.md#node-checkpoints). | Key | Env | Default | Description | | --------------------- | ------------------------------------- | ------- | ---------------------------------------------------- | | `checkpoints.enabled` | `NEURONAI_STUDIO_CHECKPOINTS_ENABLED` | `true` | Global switch for node checkpointing | | `checkpoints.ttl` | `NEURONAI_STUDIO_CHECKPOINTS_TTL` | `null` | Seconds before a checkpoint expires (`null` = never) | Purge expired checkpoints: ```bash php artisan neuronai-studio:checkpoints:purge ``` ## Templates | Key | Env | Default | Description | | ------------------- | ----------------------------------- | ------------------------------ | ----------------------------------- | | `templates_enabled` | `NEURONAI_STUDIO_TEMPLATES_ENABLED` | `true` | Enable template browser | | `template_paths` | — | package `resources/templates/` | Agent/workflow template directories | ## MCP | Key | Default | Description | | --------------------- | ----------------------- | ------------------------- | | `mcp_servers` | filesystem, telescope | Config preset MCP servers | | `mcp_stdio_allowlist` | npx, node, python, etc. | Allowed stdio commands | ## Webhooks | Key | Env | Default | Description | | ----------------------- | --------------------------------------- | ------- | -------------------------------- | | `webhook_allowed_hosts` | `NEURONAI_STUDIO_WEBHOOK_ALLOWED_HOSTS` | `*` | Host allowlist for webhook tools | | `webhook_timeout` | `NEURONAI_STUDIO_WEBHOOK_TIMEOUT` | `15` | Request timeout in seconds | ## Invoke hooks | Key | Default | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `invoke_hooks` | `[]` | Fail-closed FQCN allowlist for the canvas `invoke` node. Each class must be container-resolvable and implement `__invoke(WorkflowState): mixed`. | ## Node types | Key | Description | | ------------ | -------------------------------------------------------------------------------- | | `node_types` | Metadata (label, icon, category) for canvas palette (includes built-in `invoke`) | ## Attachments | Key | Env | Default | Description | | --------------------------- | ------------------------------------ | ------------------------------- | ------------------ | | `attachments.disk` | `NEURONAI_STUDIO_ATTACHMENTS_DISK` | `local` | Storage disk | | `attachments.path` | `NEURONAI_STUDIO_ATTACHMENTS_PATH` | `neuronai-studio/attachments` | Storage path | | `attachments.max_size_kb` | `NEURONAI_STUDIO_ATTACHMENTS_MAX_KB` | `10240` | Max upload size | | `attachments.allowed_mimes` | — | images, audio, video, pdf, text | Allowed MIME types | In workflow runs, attachments uploaded in the test harness are stored in `state.attachments` and passed to Agent/LLM nodes via `MessageFactory`. The same array persists across loop iterations for autonomous agent patterns. ## RAG | Key | Env | Default | Description | | --------------------------------- | ----------------------------------------- | ------------------------------------- | --------------------------------------- | | `rag.default_vector_store` | `NEURONAI_STUDIO_RAG_VECTOR_STORE` | `file` | Default vector store driver | | `rag.storage_path` | `NEURONAI_STUDIO_RAG_STORAGE_PATH` | `storage/app/neuronai-studio/rag` | Root path for file-based stores | | `rag.documents_disk` | `NEURONAI_STUDIO_RAG_DOCUMENTS_DISK` | `local` | Disk for persisted source files | | `rag.documents_path` | `NEURONAI_STUDIO_RAG_DOCUMENTS_PATH` | `neuronai-studio/knowledge-documents` | Relative path for uploads / pasted text | | `rag.async_ingest` | `NEURONAI_STUDIO_RAG_ASYNC_INGEST` | `true` | Queue ingest/reindex jobs from the UI | | `rag.default_embeddings_provider` | `NEURONAI_STUDIO_RAG_EMBEDDINGS_PROVIDER` | `openai` | Default embeddings provider | | `rag.default_embeddings_model` | `NEURONAI_STUDIO_RAG_EMBEDDINGS_MODEL` | `text-embedding-3-small` | Default embeddings model | | `rag.retrieval.top_k` | `NEURONAI_STUDIO_RAG_TOP_K` | `5` | Default chunks to retrieve | | `rag.retrieval.threshold` | `NEURONAI_STUDIO_RAG_THRESHOLD` | `null` | Default minimum similarity score | | `rag.chunk.max_words` | `NEURONAI_STUDIO_RAG_CHUNK_MAX_WORDS` | `200` | Ingest chunk size | | `rag.chunk.overlap_words` | `NEURONAI_STUDIO_RAG_CHUNK_OVERLAP_WORDS` | `20` | Chunk overlap | Built-in drivers: `file`, `memory`, `pinecone`, `qdrant`, `chroma`, `weaviate`, `meilisearch`, `mariadb`, `elasticsearch`, `opensearch`, `typesense`, `phpvector`. See [Vector stores](/neuronai-studio/knowledge-bases/vector-stores.md). Register custom vector stores or embeddings providers at runtime: ```php use DigitalElvis\NeuronAIStudio\Runtime\Rag\VectorStoreFactory; use DigitalElvis\NeuronAIStudio\Runtime\Rag\EmbeddingsFactory; app(VectorStoreFactory::class)->extend('my-store', function ($kb, array $options) { return new \App\Neuron\MyVectorStore(/* ... */); }); app(EmbeddingsFactory::class)->extend('custom', fn () => /* ... */); ``` Each knowledge base may override provider, model, and vector store driver independently of these defaults. ## See also * [Cost estimation](/neuronai-studio/analytics/costs.md) * [Database schema](/neuronai-studio/reference/database-schema.md) * [Publish Tags](/neuronai-studio/reference/publish-tags.md) * [Security & Access](/neuronai-studio/workflows/security-and-access.md) --- # 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/reference/configuration.md?ask=&goal= ``` `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.