README

See every connection your AI agents make.

Synapse is a development dashboard for AI agents built with the Laravel AI SDK (laravel/ai) — Telescope and Horizon, but for agents. It finds the agents in your app, lets you chat with them in the browser, and shows exactly what happened underneath: every tool call with its arguments and results, every token, every reasoning step, every error with its stack trace.

Building an agent is a tight loop — change the prompt, run it, check the tool calls, repeat. Synapse is that loop in a browser instead of tinker and dd().

Requirements


PHP	8.3+
Laravel	12 or 13
`laravel/ai`	0.9.x or 0.10.x

Installation

composer require redberry/synapse --dev

php artisan synapse:install

That publishes config/synapse.php, runs the migrations, and installs a SynapseServiceProvider into your app — which is where the access gate lives. Then open /synapse.

You never run npm. Compiled assets ship inside the package and are inlined into the dashboard, so there is no publish step and a composer update can never leave you on stale assets.

Synapse reads your existing config/ai.php. You don't configure providers or API keys in Synapse; if your agents run in your app, they run here and vice versa.

⚠️ Read this before deploying anything

Synapse exposes an endpoint that invokes your real agents. It spends real API credits and executes your real tools, which may write to your database, call webhooks, or do anything else your tool code does.

Two independent protections, both on by default:

It does not register at all in production unless you explicitly set SYNAPSE_ENABLED=true.

Outside local, every route — dashboard and API — passes the viewSynapse gate, which denies everyone until you say otherwise:

// app/Providers/SynapseServiceProvider.php
Gate::define('viewSynapse', function ($user) {
    return in_array($user->email, [
        'you@example.com',
    ]);
});

In local, the dashboard is open and needs no authentication — that's the point of a dev tool.

What you get

Discovery — every agent class in your app, with its provider, model and tools. Write a class, refresh, it's there.
Chat playground — streaming replies, attachments, a model selector for trying another model without touching your code, and full conversation persistence.
Tool inspection — each call inline as a card: arguments, results, duration, and failures marked as failures. Provider-native tools are distinguished from your own.
Info panel — the agent's resolved config, system prompt, tool schemas and middleware, exactly as the SDK would use them.
History — search, filter, replay, rename and delete past conversations.
Errors — anything that throws becomes an inline card with the exception class, message and stack trace. Never a dead stream or a raw 500.

Configuration

Everything is optional; the defaults work.

Key	Env	Default	What it does
`enabled`	`SYNAPSE_ENABLED`	`true` except in production	Master switch. Routes don't register when false.
`ui.path`	`SYNAPSE_PATH`	`synapse`	Where the dashboard is mounted.
`ui.middleware`	—	`['web']`	Middleware on every Synapse route. The gate is added on top.
`discovery.paths`	—	`app/Ai/Agents`, `app/Agents`	Where to look for agent classes. An agent outside these is invisible — the usual reason a Discovery page is empty.
`discovery.ignore`	—	`[]`	Agent classes to hide.
`playground.models`	—	`[]`	Extra models in the composer's selector, on top of the agent's own and its provider's cheapest/smartest.
`storage.connection`	`SYNAPSE_DB_CONNECTION`	app default	Database connection for Synapse's tables.
`storage.attachments_disk`	`SYNAPSE_ATTACHMENTS_DISK`	`local`	Disk for files uploaded in the playground.
`retention.auto_prune`	`SYNAPSE_AUTO_PRUNE`	`false`	Schedule a daily prune.
`retention.days`	`SYNAPSE_PRUNE_DAYS`	`7`	How long conversations live when auto-pruning.

Commands

Command	What it does
`synapse:install`	Publishes config, migrations and the gate provider, then migrates. Safe to re-run — it never overwrites your edits.
`synapse:prune`	Deletes conversations older than `--days`, with their attachments.
`synapse:clear`	Deletes all Synapse conversations and attachments.

php artisan about shows Synapse's version, whether it's enabled, its path, how many agents it found, and its retention setting.

Runtimes

The playground streams replies as the model produces them, which needs PHP to be serving HTTP directly.

Runtime	Streaming
`php artisan serve`	✅ Verified
nginx + PHP-FPM (Herd, Valet, Forge)	✅ Verified
Laravel Sail	✅ Expected — same stack
FrankenPHP	✅ Verified
Laravel Octane	❌ Not supported in v0.1.0

Octane's workers run under PHP's CLI interface, where output cannot be pushed to a client mid-request, so replies arrive complete instead of streaming. Nothing breaks — Synapse detects it and says so in the playground rather than leaving you looking at a blank thread. It isn't tested per release yet, so it isn't claimed as supported.

GOAL.md is the full manual — every feature, every config key, access control, where your data lives, and a troubleshooting section.

Development

composer install && npm install

npm run build      # compile assets into dist/ (committed; inlined at runtime)

composer check     # lint + static analysis + tests

composer test:e2e  # browser end-to-end tests (needs Playwright; not run in CI)

Run composer hooks once to enable the pre-commit hook. See DEV.md for the development cycle and AGENTS.md for architecture and coding standards.

License

MIT — see LICENSE.md.

redberry / synapse

Maintainers

Package info

Statistics

Security