Filament Terminal Console Laravel Package

Getting Started

Install the package with Composer and register the plugin on the Filament panel where operators should have access:

composer require filaforge/filament-terminal-console
php artisan vendor:publish --tag="filament-terminal-console-config"

Then add the plugin to your panel provider:

->plugin(TerminalConsolePlugin::make())

Look first at the published config file and the plugin class — the command allow-list and the authorization gate are the two settings that determine whether the console is safe to expose. The first practical use case is running routine Artisan commands (php artisan about, cache:clear, queue:restart, migrate:status) from the admin UI during incidents instead of opening an SSH session. Because this is a v0.1.x package, start with a single non-production panel and a short allow-list before wiring it into anything operational.

Implementation Patterns

• Gate by panel and role. Register the plugin only on your admin/ops panel and combine it with Filament's authorization (->authorize() or a dedicated viewTerminalConsole gate). Do not rely on panel access alone.
• Environment-scope registration. Wrap plugin registration in an environment check (local, staging) or an explicit TERMINAL_CONSOLE_ENABLED flag so production is off unless deliberately turned on.
• Whitelist commands. Treat the config allow-list as the primary control surface. Add custom commands as explicit entries rather than exposing a free-form shell.
• Audit executions. Log the authenticated user, command, timestamp, exit code, and truncated output. A model event or a small middleware/service wrapper around the executor gives you a defensible audit trail.
• Separate ops access from app admin. If you have multiple panels, expose the terminal only on the operations panel; keep it out of the general admin panel used by content editors.
• Extend via config and custom commands. Register project-specific Artisan commands and reference them in the allow-list rather than shelling out to arbitrary binaries.
• Test with a fake executor. In feature tests, bind a fake terminal service so tests assert authorization and command dispatch without spawning real processes.

Gotchas and Tips

• Security is the dominant risk. Any console that accepts input can become remote code execution. Enforce the allow-list, escape arguments, and never run as root or a privileged system user.
• Config caching. After editing the allow-list or gate, run php artisan config:clear (and config:cache in deploy) — stale cached config is a common source of "my change did nothing."
• Blocking workers. Long-running commands tie up PHP-FPM workers and can hit request timeouts. Set conservative timeouts and prefer dispatching long jobs to the queue.
• Output handling. Large outputs get truncated or buffered; stream or cap output rather than dumping megabytes into the response.
• Filesystem and PATH differences. The web user's PATH and working directory differ from your SSH shell. Use absolute paths to php and artisan, and verify permissions on storage/ and bootstrap/cache/.
• Container paths. In Docker, the app path seen by the web process may not match your local path; confirm the command's working directory in the config.
• Pre-1.0 versioning. v0.1.x makes no stability guarantees. Pin the exact version in composer.json and review each patch before upgrading; the v0.1.2 changelog is sparse, so diff the source if you depend on internal APIs.
• Debugging. Check storage/logs/laravel.log, confirm the plugin is registered on the correct panel, and verify the gate/policy is returning true for the current user before assuming a package bug.
• Extension points. The config allow-list, custom command registry, and publishable views are the intended customization seams — prefer those over editing vendor files.