README

A Laravel package for managing local and remote servers through an interactive shell. Features include SSH connections, real-time terminal access via WebSockets, session sharing, and a complete React-based web interface.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Features

🖥️ Local & Remote Server Management - Connect to any server via SSH or manage the local server
🔐 Multiple Authentication Methods - Support for password and SSH key authentication
🚀 Real-time Terminal - Interactive terminal with WebSocket support using Laravel Reverb
👥 Session Sharing - Share terminal sessions with other users with view/execute permissions
🌐 RESTful API - Complete API for headless operation
⚛️ React Frontend - Optional React-based web interface with Inertia.js
🔒 Security - Encrypted credential storage, authorization policies, and access gates
📝 Command History - Track all executed commands with output

Requirements

PHP 8.3+
Laravel 10, 11, or 12
Optional: Laravel Reverb for WebSocket support
Optional: SSH2 PHP extension for better performance

Installation

Quick Install

composer require metacomet-technologies/server-manager
php artisan server-manager:install

That's it! 🎉 The package comes with pre-built assets and requires no npm installation or build steps.

What Makes This Different?

Server Manager is completely self-contained:

✅ No npm install required - All assets are pre-built and served from the package
✅ No build step needed - Works immediately after installation
✅ No conflicts - Runs as a separate Inertia app alongside your existing pages
✅ Zero frontend configuration - Everything works out of the box

Manual Installation

Install the package:

composer require metacomet-technologies/server-manager

Publish and run migrations:

php artisan vendor:publish --tag="server-manager-migrations"
php artisan migrate

(Optional) Publish the configuration:

php artisan vendor:publish --tag="server-manager-config"

(Optional) Configure Laravel Reverb for WebSockets:

composer require laravel/reverb
php artisan reverb:install

Configuration

After installation, configure the package in config/server-manager.php:

// SSH driver: 'phpseclib' or 'ssh2'
'ssh_driver' => env('SERVER_MANAGER_SSH_DRIVER', 'phpseclib'),

// Web interface settings
'web' => [
    'enabled' => true,
    'prefix' => 'server-manager', // Access at yourapp.com/server-manager
    'middleware' => ['web', 'auth'],
],

// Local server access gate
'local_server_gate' => 'server-manager:access-local',

Setting up the Local Server Access Gate

Define the gate in your AuthServiceProvider:

Gate::define('server-manager:access-local', function ($user) {
    return $user->hasRole('admin'); // Or your own logic
});

Usage

Web Interface

After installation, visit yourapp.com/server-manager to access the web interface.

API Usage

use Metacomet\ServerManager\Facades\ServerManager;

// Create a server
$server = ServerManager::createServer([
    'user_id' => auth()->id(),
    'name' => 'Production Server',
    'host' => '192.168.1.100',
    'username' => 'deploy',
    'auth_type' => 'key',
    'private_key' => file_get_contents('/path/to/key'),
]);

// Create a session
$session = ServerManager::createSession(
    auth()->id(),
    $server,
    'Deployment Session'
);

// Execute commands
$result = ServerManager::execute($session, 'ls -la');
echo $result['output'];

API Endpoints

# Servers
GET    /api/server-manager/servers
POST   /api/server-manager/servers
GET    /api/server-manager/servers/{id}
PUT    /api/server-manager/servers/{id}
DELETE /api/server-manager/servers/{id}
POST   /api/server-manager/servers/{id}/test-connection

# Sessions
GET    /api/server-manager/sessions
POST   /api/server-manager/sessions
GET    /api/server-manager/sessions/{id}
DELETE /api/server-manager/sessions/{id}
POST   /api/server-manager/sessions/{id}/share
DELETE /api/server-manager/sessions/{id}/share/{userId}

# Commands
POST   /api/server-manager/sessions/{id}/execute
POST   /api/server-manager/sessions/{id}/execute-async
GET    /api/server-manager/sessions/{id}/processes/{processId}/output
GET    /api/server-manager/sessions/{id}/processes/{processId}/status
DELETE /api/server-manager/sessions/{id}/processes/{processId}
GET    /api/server-manager/sessions/{id}/history

WebSocket Support

For real-time terminal functionality, start Laravel Reverb:

php artisan reverb:start

The package will automatically use WebSockets when available.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Development

Building Assets

npm install
npm run build

Running Tests

composer test

Releasing a New Version

We provide a release script that handles the entire release process:

# Bump patch version (1.0.0 -> 1.0.1)
./release.sh

# Bump minor version (1.0.0 -> 1.1.0)
./release.sh minor

# Bump major version (1.0.0 -> 2.0.0)
./release.sh major

The release script will:

Run tests and static analysis
Build frontend assets
Create and push a git tag
Trigger GitHub Actions for release

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

metacomet-technologies / server-manager

Maintainers

Details