Download the PHP package mwguerra/web-terminal without Composer

Web Terminal

A secure web terminal package for Laravel with Filament integration. Execute allowed commands on local systems or SSH servers.

Version Compatibility

Features

• Connection types: Local shell execution or SSH connections to remote servers
• Command whitelisting: Configurable allowlist to restrict which commands can be executed
• Interactive mode: PTY/tmux sessions for artisan tinker, reverb:start, queue:work, and other interactive/long-running commands
• Stream mode: Full interactive PTY shell via WebSocket with ghostty-web canvas rendering — supports vim, htop, and other full-screen TUI apps
• Enum-based permissions: TerminalPermission enum for clean, declarative permission control
• Scripts: Define reusable command sequences with progress tracking and one-click execution
• Comprehensive logging: Audit trail for connections, commands, outputs, and errors
• Multi-tenant support: Built-in tenant isolation for SaaS applications
• Session management: Inactivity timeout, disconnect-on-navigate, and session statistics
• Filament integration: Terminal page and Terminal Logs resource with stats widgets
• Embeddable: Use as Livewire component or Filament Schema component in any page
• Clipboard integration: Copy All button, per-block copy on hover, multi-line paste with confirmation
• Security by design: Credential protection, input sanitization, rate limiting
• Localization: English and Portuguese (BR) translations included
• Dark mode: Full dark mode support via Filament

Requirements

• PHP 8.3+
• Laravel 12.x or 13.x
• Filament 5.x
• Livewire 4.x

For Laravel 11 and Filament 4 support, use version ^1.0.

Warning

This package provides real shell access to real servers. Commands executed through this terminal can modify files, change configurations, and affect running services.

Before using this package:

• Restrict access to technical personnel only — do not expose terminal pages to general users
• Review and limit the allowed commands whitelist for each terminal instance
• Enable logging to maintain an audit trail of all executed commands
• Test configurations in a safe environment before deploying to production

Use at your own risk. The authors are not responsible for any damage, data loss, or security incidents resulting from the use of this package. Always ensure proper access controls and review your security configuration.

Installation

For Filament 5 / Laravel 12–13 (latest)

For Filament 4 / Laravel 11 (legacy)

Upgrading from v1.x to v2.x

Key changes in v2.x:

• Requires Laravel 12.x or 13.x, Filament 5.x, and Livewire 4.x
• If you published Blade views, update any @entangle('prop') to $wire.entangle('prop') in your custom views

Interactive Setup

Run the install command for guided configuration:

The installer will:

• Publish configuration file
• Publish database migration (with optional tenant support)
• Optionally publish Blade views for customization
• Optionally run the migration

Install Options

Non-Interactive Installation

Use --no-interaction (or -n) with specific flags to skip prompts:

Note: When using -n without any flags, the installer defaults to --config --migration.

Generate Custom Pages

Generate customizable Terminal page and TerminalLogs resource in your application instead of using the plugin defaults:

The generated files are placed in directories configured in your panel provider via ->discoverPages() and ->discoverResources(). For example:

Important: When using custom generated pages with the plugin, you must disable the corresponding plugin defaults to avoid duplicate pages in your navigation.

If you don't need the plugin at all (using only custom pages), you can remove WebTerminalPlugin::make() from your panel provider entirely.

Terminal Command Permissions

When generating a custom Terminal page, you can specify command permissions:

Create Terminal Page Command

For more control over page generation, use the dedicated terminal:make-page command:

Interactive prompts (when not using --no-interaction):

1. Panel selection - if multiple panels exist
2. Page class name - defaults to "Terminal"
3. Terminal key - auto-generated from name (e.g., server-terminal-terminal)
4. Command permissions - secure/none/all options

Manual Setup

If you prefer manual setup:

Quick Start

Get a working terminal in under a minute:

That's it! Visit /admin/terminal to access the terminal.

For a custom terminal with specific commands:

Filament Integration

The package provides a Filament plugin that adds:

• Terminal Page: A demo page with local terminal functionality
• Terminal Logs Resource: Browse and search terminal session logs with stats widgets

Register the Plugin

Add the plugin to your Filament panel provider:

Plugin Configuration

Customize Navigation

Disable Components

Access Plugin Configuration

Customizing the Plugin's Terminal Page

The plugin provides a ready-to-use Terminal page at /admin/terminal. To customize its terminal configuration (allowed commands, working directory, etc.), create your own page that extends the base:

Then disable the plugin's default page and register your custom one:

Usage

Option 1: Direct Livewire Component

Embed the terminal directly in any Blade view:

Option 2: Filament Schema Component (Recommended)

Use the schema component for Filament pages with fluent configuration:

View file (resources/views/filament/pages/terminal.blade.php):

Default Allowed Commands

The package uses command whitelisting for security. Only commands in the whitelist can be executed.

Config File Defaults

The config/web-terminal.php file includes these default allowed commands:

Note: The * wildcard allows the command with any arguments (e.g., cd /var/log, uname -a, grep pattern file.txt).

Plugin Terminal Page Defaults

The Filament plugin's Terminal page (/admin/terminal) uses an extended command set suitable for Laravel development:

Note: The * wildcard allows the command with any arguments (e.g., php artisan migrate, composer require package/name).

Customizing Commands

Override the defaults per-terminal using allowedCommands():

Or bypass the whitelist entirely (use with caution):

Configuration Options

Dynamic Configuration with Closures

All configuration methods accept Closures for dynamic resolution at runtime. This is useful for:

• Resolving values based on the authenticated user
• Loading configuration from the database or external sources
• Conditional logic based on current state

Connection Types

Local Connection

SSH Connection with Password

SSH Connection with Array Configuration

Use an array to configure SSH connections, useful when loading configuration dynamically:

SSH Connection with Key

The key parameter accepts the private key content directly. Load it using your preferred method:

Generic Connection (Advanced)

For complex configurations, use the connection() method with a config array or ConnectionConfig object:

Terminal Settings

UI Settings

Stream Mode

Stream mode provides a full interactive PTY shell via WebSocket, powered by ghostty-web. Unlike the Classic terminal (which executes one command at a time via Livewire), Stream mode gives you a real shell session with canvas-rendered output — supporting full-screen TUI apps like vim, htop, nano, and more.

Enabling Stream Mode

In dual-mode, a toggle pill in the header bar lets users switch between Classic and Stream modes.

Stream Mode Settings

Stream mode always auto-connects when the terminal becomes visible. The connect/disconnect button is never shown in Stream mode.

WebSocket Server

Stream mode requires a WebSocket server to bridge the browser to a PTY shell process. Start it with:

Options:

The server uses React PHP for the event loop and Ratchet RFC6455 for WebSocket protocol handling.

SSL/WSS Configuration

When your app is served over HTTPS, the WebSocket connection must use WSS. Configure SSL in your .env:

Or configure in config/web-terminal.php:

When ssl_cert and ssl_key are set, the WebSocket server automatically serves over TLS.

Required Dependencies

Stream mode requires additional packages (suggested, not required by default):

Running in Production

For production, run the WebSocket server as a supervised process:

Or with systemd:

Session Management

Control how the terminal handles navigation and inactivity:

Session Configuration in Config File

You can also configure these settings globally in config/web-terminal.php:

The terminal tracks user activity (commands, keystrokes) and automatically disconnects after the configured timeout period. This helps prevent orphaned tmux sessions and releases server resources.

Environment Helpers

Preset Configurations

Quick presets that configure allowed commands for common use cases:

Note: Presets can be combined with other methods:

Scripts

Scripts allow you to define reusable sequences of commands that can be executed with a single click. They appear in a dropdown menu in the terminal header and provide visual feedback during execution.

Defining Scripts

Use the Script class to define scripts with a fluent API:

Script Configuration Options

Execution Behavior

Elevated Scripts

Scripts can bypass the command whitelist using the elevated() method. Use this for trusted administrative scripts:

Warning: Elevated scripts bypass all command authorization checks. Only use for trusted scripts that require commands not in your whitelist.

Disconnection Scripts

For scripts that will disconnect the terminal (like server reboots), use the willDisconnect() method:

Script Authorization

Scripts are only shown in the dropdown if the user is authorized to run them. Authorization is determined by:

1. Elevated scripts: Always authorized (bypass whitelist)
2. Terminal allows all commands: Always authorized
3. Command whitelist: All script commands must be in the allowedCommands list

Script Execution UI

When a script runs, a slide-over panel displays:

• Script name and progress percentage
• Progress bar
• List of all commands with status icons
• Execution time for each command
• Exit codes for completed commands
• Cancel button to stop execution

Note: Terminal input is disabled while a script is running to prevent interference with script execution. The input field is re-enabled once the script completes or is cancelled.

Command statuses:

• Pending: Waiting to execute
• Running: Currently executing
• Success: Completed with exit code 0
• Failed: Completed with non-zero exit code
• Skipped: Not executed (due to stopOnError or cancellation)

Script Examples

Deployment Script

Log Viewer Script

Database Backup Script

Server Maintenance Script

Logging

The package includes comprehensive logging for terminal sessions, connections, and command execution.

Configuration

Logging is configured in config/web-terminal.php:

Fluent API

Override logging settings per-terminal using the log() method:

Array and Closure Configuration

The log() method also accepts an array or Closure, which is useful for dynamic configuration and adding custom metadata:

Log Configuration Options

Standalone Metadata Method

You can also set metadata separately using the logMetadata() method:

This is useful when you want to keep log settings separate from metadata, or when building configurations dynamically.

Event Types

The logger tracks these event types:

• connected - Terminal session started
• disconnected - Terminal session ended
• command - Command executed
• output - Command output (when enabled)
• error - Error occurred
• blocked - Command was blocked by whitelist

Session Info Panel

When logging is enabled, the terminal info panel displays session statistics:

• Session ID
• Commands Run
• Session Duration
• Error Count

Querying Logs

Available Scopes

Log Cleanup

Clean up old log entries manually:

Multi-Tenant Support

For multi-tenant applications, configure the tenant resolver:

Or use a class-based resolver:

The resolver class must implement __invoke():

Built-in Commands

The terminal includes these built-in commands:

• help - Show available commands
• clear - Clear terminal output
• history - Show command history

Copy & Paste

The terminal includes clipboard integration for copying output and pasting commands.

Copy All Output

Click the clipboard icon in the terminal header bar to copy the entire terminal output as plain text. ANSI escape codes are stripped automatically. A brief checkmark feedback confirms the copy.

Per-Block Copy

Hover over any command block (a command and its output) to reveal a copy button. Click it to copy that block's content to the clipboard.

Multi-Line Paste

When you paste text containing multiple lines into the terminal input:

• A confirmation modal appears listing all commands to be executed
• Comment lines (starting with #) and empty lines are filtered out
• Commands are executed sequentially with visual progress feedback
• You can cancel at any time before or during execution

Single-line pastes are inserted directly into the input field without a modal.

Note: Multi-line paste is disabled during interactive mode (e.g., when a process like top is running) and during script execution.

Programmatic Access

Security by Design

WebTerminal is built with security as a core principle, implementing multiple layers of protection to minimize attack surface and prevent credential exposure.

Credential Protection

Server-Side Only Credentials: SSH passwords, private keys, and passphrases are stored exclusively in protected PHP properties that are never serialized or sent to the browser. This prevents:

• Credential exposure in HTML page source
• Credential leakage in Livewire AJAX requests
• JavaScript access to sensitive authentication data
• Browser DevTools inspection of credentials

The connection details shown in the info panel (host, port, username) are rendered server-side via PHP methods, not exposed as JavaScript-accessible properties.

Command Filtering

Commands are validated server-side against a configurable allowlist before execution. This provides defense-in-depth against:

• Command injection attacks
• Unauthorized system access
• Privilege escalation attempts

Only whitelisted commands can be executed (unless allowAllCommands() is explicitly used).

Shell Operator Controls

By default, the terminal blocks shell operators (pipes, redirections, chaining, and variable expansion) to prevent command injection. You can selectively enable operator groups based on your security requirements.

Operator Groups

Usage Examples

Interactive Mode

By default, commands run synchronously — they execute, wait for completion, and return the output. This works for simple commands like ls or pwd, but fails for:

• REPL commands like php artisan tinker (needs stdin input)
• Long-running processes like php artisan reverb:start or php artisan queue:work (timeout)
• Interactive installers like composer create-project (needs user input)

Enable interactive mode to use PTY/tmux sessions with streaming output and stdin support:

When allowInteractiveMode() is enabled:

• Commands still go through the whitelist validation
• Execution uses tmux/PTY sessions instead of synchronous Symfony Process
• Output streams in real-time via polling (500ms intervals)
• Users can send stdin input during execution
• TUI detection still blocks full-screen apps (vim, htop, etc.)

Permissions with TerminalPermission Enum

Instead of chaining multiple allow*() methods, use the allow() method with the TerminalPermission enum:

Available permissions:

Security Invariants

Regardless of which operator groups you enable, the following characters are always blocked to prevent fundamental injection attacks:

• Null bytes (\x00) - Can truncate strings and bypass security checks
• Newlines (\n) - Can inject additional commands on new lines
• Carriage returns (\r) - Can be used for command injection via line manipulation

Why Operators Are Blocked by Default

Shell operators are a common vector for command injection attacks. Even when commands are whitelisted, operators can be used to chain arbitrary commands, redirect sensitive data to files, or substitute variables to bypass restrictions. By blocking operators by default and requiring explicit opt-in, the terminal follows the principle of least privilege and reduces the attack surface for untrusted input.

Input Sanitization

All user input is properly escaped and sanitized:

• Commands are validated against the whitelist before execution
• Output is escaped before display to prevent XSS
• Environment variables are filtered

Session Security

• Terminal sessions use secure UUIDs
• Sessions can be configured to disconnect on page navigation
• Inactivity timeout support for automatic disconnection
• All session events can be logged for audit purposes

Audit Logging

Optional comprehensive logging captures:

• Connection events (connect/disconnect)
• Command execution with exit codes and timing
• Blocked command attempts (security events)
• User and session identification

Logging can be configured per-terminal and respects output truncation limits.

Security Best Practices

1. Use allowedCommands(): Always restrict commands to only what's needed
2. Avoid allowAllCommands(): Only use in controlled development environments
3. Enable logging: Track terminal usage for security auditing
4. Use SSH keys: Prefer key-based authentication over passwords when possible
5. Set timeouts: Configure inactivity timeouts to limit exposure
6. Restrict access: Use Filament policies or middleware to limit who can access terminal pages

Rate Limiting

Configure rate limiting in the config file:

The default settings allow 1 command per second per user. Adjust based on your use case:

Events

The package dispatches events you can listen to:

• MWGuerra\WebTerminal\Events\CommandExecutedEvent - After command execution
• MWGuerra\WebTerminal\Events\TerminalConnectedEvent - When terminal connects
• MWGuerra\WebTerminal\Events\TerminalDisconnectedEvent - When terminal disconnects

Example listener:

Example Use Cases

Server Monitoring Dashboard

Developer Sandbox

Docker Container Management

Database Admin (Read-Only)

Multi-Tenant SaaS

Localization

The package includes translations for English (en) and Brazilian Portuguese (pt_BR). All UI labels, messages, and Filament resource strings are translatable.

Publishing Language Files

To customize translations, publish the language files:

This will copy the language files to lang/vendor/web-terminal/.

Using Translations

Translations use the web-terminal::terminal namespace:

Available Translation Keys

Adding New Languages

Create a new directory in lang/ with your locale code and copy the structure from en/terminal.php:

Issues and Contributing

Found a bug or have a feature request? Please open an issue on GitHub Issues.

We welcome contributions! Please read our Contributing Guide before submitting a pull request.

License

Web Terminal is open-sourced software licensed under the MIT License.

Author

Marcelo W. Guerra

• Website: mwguerra.com
• Github: mwguerra
• Linkedin: marcelowguerra