> 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/workflows/security-and-access.md).

# Security & Access

NeuronAI Studio includes gate-based authorization, middleware protection, and security controls for webhook and MCP integrations.

## Authorization gate

All studio routes pass through the `neuronai-studio.auth` middleware, which checks the configured gate.

```php
// config/neuronai-studio.php
'gate' => 'viewNeuronAIStudio',
'middleware' => ['web', 'neuronai-studio.auth'],
```

### Default behavior

| Environment | Access                         |
| ----------- | ------------------------------ |
| `local`     | Open to all (no auth required) |
| Other       | Requires authenticated user    |

### Custom gate

Define in `AppServiceProvider`:

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

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

```mermaid
flowchart LR
    Request[HTTP Request] --> Middleware[neuronai-studio.auth]
    Middleware --> Gate{viewNeuronAIStudio?}
    Gate -->|yes| Studio[Studio UI]
    Gate -->|no| Deny[403 Forbidden]
```

## Webhook security

Webhook tools validate target hosts against an allowlist:

```env
NEURONAI_STUDIO_WEBHOOK_ALLOWED_HOSTS=api.example.com,hooks.slack.com
```

Default `*` allows all hosts — **change this in production** to prevent SSRF.

Timeout limit:

```env
NEURONAI_STUDIO_WEBHOOK_TIMEOUT=15
```

## MCP security

### Stdio command allowlist

Only commands in the allowlist can spawn MCP processes:

```php
'mcp_stdio_allowlist' => ['npx', 'node', 'python', 'python3', 'uv', 'uvx'],
```

An empty array allows all commands.

### HTTP token auth

HTTP MCP servers use `token_env` to reference bearer tokens from `.env` — never hardcode secrets in config files.

## Invoke node hooks

The canvas **Invoke** node may only call FQCNs listed in `invoke_hooks` (empty = nothing allowed):

```php
'invoke_hooks' => [
    \App\Neuron\Hooks\EnrichLead::class,
],
```

Each class must be resolvable from the container and implement `__invoke(\NeuronAI\Workflow\WorkflowState $state): mixed`. See [Logic Nodes — Invoke](/neuronai-studio/workflows/logic-nodes.md#invoke).

## Builder tools

Builder tools store a PHP **invoke body** in the database for prototyping. Studio does **not** `eval()` that body at runtime. Execution requires CodeGen **export**, which writes a PHP class under `export_path` and sets `config.class_path`; `ToolResolver` then instantiates that class.

| Control               | Recommendation                                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow_builder_tools` | Default `true` only when `APP_ENV=local`. Keep **off** in production so the UI cannot create/edit builder tools                                   |
| CodeGen export        | Keep off outside local — export is what writes executable PHP to disk                                                                             |
| Studio gate           | Restrict who can open `/neuronai-studio` (anyone with access + CodeGen on can plant PHP under `export_path`)                                      |
| Production tools      | Prefer scanned PHP classes / [Make Tool CLI](/neuronai-studio/tools/make-tool-cli.md) or [Webhook Tools](/neuronai-studio/tools/webhook-tools.md) |

```env
NEURONAI_STUDIO_ALLOW_BUILDER_TOOLS=false
```

Already-exported classes with `class_path` continue to resolve when the flag is off — they are normal application PHP, not dynamic DB evaluation.

See [Builder Tools](/neuronai-studio/tools/builder-tools.md).

## Approving sensitive tools

Agents can call tools that perform destructive or high-impact actions (deleting files, transferring money, sending emails). **Tool approval** adds a human gate: when enabled on an agent (or overridden on a workflow Agent node), execution pauses before any tool runs and requires an explicit approve/reject decision in the workflow test harness.

| Control             | Recommendation                                                                                                                     |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Destructive tools   | Enable **Require tool approval** on agents that can delete, pay, or externally message                                             |
| Review payload      | Inspect the tool name and arguments in the approval card before approving                                                          |
| Rejections          | Wire a `rejected` handle on the Agent node so denied actions branch to a safe path instead of silently continuing                  |
| Tool implementation | Use class-based tools — the paused interrupt is serialized into the checkpoint and inline `Closure` callbacks cannot be serialized |

> Approval currently gates **all** tools an agent requests (there is no per-tool allowlist yet), so enable it for agents whose entire tool surface warrants oversight.

See [Human-in-the-Loop → Tool approval](/neuronai-studio/workflows/human-in-the-loop.md#tool-approval) and [Creating Agents → Tool approval](/neuronai-studio/agents/creating-agents.md#tool-approval).

## Production recommendations

| Control            | Recommendation                                                                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Studio access      | Restrict gate to admin/developer roles                                                                                                                                        |
| Environment        | Disable open access outside `local`                                                                                                                                           |
| CodeGen            | Keep `codegen.*` off outside local (or enable selectively); see [Export & Production](/neuronai-studio/workflows/export-and-production.md#codegen-feature-flags)              |
| Builder tools      | Keep `allow_builder_tools` off outside local; use classes or webhooks in prod                                                                                                 |
| Long workflow runs | Enable async queue runs — sync SSE can 504 under FPM/proxy timeouts; see [Runtime & Traces](/neuronai-studio/workflows/runtime-and-traces.md#long-running-runs-under-php-fpm) |
| Webhooks           | Set explicit host allowlist                                                                                                                                                   |
| MCP stdio          | Keep command allowlist minimal                                                                                                                                                |
| Invoke hooks       | Keep `invoke_hooks` minimal (fail-closed)                                                                                                                                     |
| Attachments        | Use dedicated disk with size limits                                                                                                                                           |
| API keys           | Keep in `config/neuron.php` / `.env` only                                                                                                                                     |
| Sensitive tools    | Require tool approval for destructive agent actions                                                                                                                           |

## CodeGen

Code generation (export to disk, class preview, `make-tool`, import-to-studio) is controlled by `neuronai-studio.codegen` flags. Defaults are on only in `local`. In staging/production leave them off unless you intentionally allow developers to write PHP under `export_path`.

Already-exported classes continue to resolve at runtime regardless of these flags.

## File uploads

Attachment uploads respect:

* `max_size_kb` — default 10 MB
* `allowed_mimes` — restricted file types
* Laravel disk configuration

## Related code

* `EnsureNeuronAIStudioAuthorized` middleware
* `NeuronAIStudioServiceProvider::registerGate()`
* `WebhookTool` — host validation

## See also

* [Installation](/neuronai-studio/getting-started/installation.md#authorization)
* [Webhook Tools](/neuronai-studio/tools/webhook-tools.md)
* [MCP Stdio & HTTP](/neuronai-studio/mcp-servers/stdio-and-http.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/workflows/security-and-access.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.