FastControl

Personal server & project management dashboard with AI assistant
One-click Docker commands, SSH terminals, git operations, and natural language AI control.

Features • Screenshots • Installation • Spotlight App • Usage

---

About

FastControl is a localhost dashboard for developers who manage multiple servers and projects. Instead of juggling terminal windows and remembering Docker commands, FastControl provides a clean web interface for common operations. Ekran görüntülerini yüklemeye üşendim, o yüzden şimdilik yoklar. Built for personal use, it runs entirely on your machine with no external dependencies or cloud services. Your server credentials stay local and encrypted.

Created by Umut Piynar

Features

Server Management

• Server Dashboard — Add, edit, and organize your servers with custom labels and working directories
• SSH Terminal — Full interactive terminal sessions via xterm.js, right in your browser
• SSH Key Management — Generate ed25519/RSA keys, deploy to servers with one click
• Docker Controls — Execute docker-compose commands: down, build, up, ps, logs
• Real-time Log Streaming — View container logs live via WebSocket connection
• Git Operations — Pull latest changes or clone repos directly on remote servers

Local Projects

• Multi-Directory Scanning — Configure multiple directories to scan for git repos (default: ~/Documents)
• Clone from GitHub — Paste a URL and clone with stored credentials
• Quick Git Actions — Add, commit, and push with configurable commit messages
• One-Click Deploy — Combined add + commit + push in a single action

AI Assistant

• Natural Language Control — Ask the AI to manage your servers in plain English
• Google Gemini Powered — Uses gemini-1.5-flash with function calling
• Read + Confirm Model — AI can read data freely, but actions require your approval
• Collapsible Sidebar — Access AI from any tab via the sidebar on the right
• Smart Functions — List servers, run commands, Docker operations, git pull

Security

• Localhost Only — Binds to 127.0.0.1, never exposed to network
• Encrypted Credentials — GitHub PAT and Gemini API key stored with AES-256-CBC encryption
• Key-Based SSH — No passwords stored, uses SSH key authentication only
• AI Action Confirmation — All AI-initiated commands require explicit user approval

Screenshots

Server Dashboard — Manage all your servers in one place

SSH Terminal — Interactive terminal sessions in the browser

Docker Logs — Real-time log streaming from containers

Local Projects — Quick git operations on local repositories

Tech Stack

Layer	Technology
Backend	Hono + TypeScript + WebSocket
Frontend	React + TypeScript + CSS Modules
API	Hono RPC (type-safe client)
AI	Google Gemini API (gemini-1.5-flash) with function calling
SSH	ssh2
Terminal	xterm.js
Validation	Zod
Storage	Local JSON files (encrypted sensitive data)

Installation

Prerequisites

• Node.js 18+
• SSH key pair (~/.ssh/id_ed25519 or ~/.ssh/id_rsa)
• GitHub Personal Access Token (for git operations)

Setup

# Clone the repository
git clone https://github.com/uruskan/fastControl.git
cd fastControl

# Install dependencies
npm install

# Start development server
npm run dev

The app will be available at:

• Frontend: http://localhost:3000
• API Server: http://localhost:5555

Production Build

npm run build
npm start

macOS Spotlight App

You can create a native macOS app that launches FastControl from Spotlight, complete with a custom icon.

Creating the App

1. Open Script Editor (search "Script Editor" in Spotlight)

2. Paste this AppleScript:

on run
    set appDir to "/path/to/fastControl"  -- Change this to your path

    -- Check if server is already running
    try
        do shell script "lsof -i :5555 > /dev/null 2>&1"
        -- Server running, just open browser
        do shell script "open http://localhost:3000"
    on error
        -- Start the server
        tell application "Terminal"
            activate
            do script "cd \"" & appDir & "\" && npm run dev"
        end tell

        -- Wait for server to start
        delay 3

        -- Open browser
        do shell script "open http://localhost:3000"
    end try
end run

3. Save as Application:

   • File → Export
   • File Format: Application
   • Name: FastControl
   • Location: ~/Applications (or /Applications)

4. Add Custom Icon:

   • Find the saved FastControl.app
   • Right-click → Get Info
   • Drag the icon image onto the icon in the top-left of the info window
   • (You can use the SVG at docs/icon.svg, convert to PNG/ICNS first)

5. Use from Spotlight:

   • Press Cmd + Space
   • Type "FastControl"
   • Press Enter to launch

The app intelligently checks if the server is already running before starting a new instance.

Usage

First-Time Setup

1. Configure GitHub Credentials

   • Go to Settings tab
   • Enter your GitHub username and Personal Access Token
   • Credentials are encrypted and stored locally

2. Set Up SSH Keys

   • Go to Servers tab → SSH Keys section
   • Generate a new key if you don't have one
   • Deploy to your servers for passwordless access

3. Add Your Servers

   • Click "Add Server" in the Servers tab
   • Enter hostname, user, port, and working directory
   • The working directory is where Docker and git commands run

4. Configure AI Assistant (optional)

   • Click the "AI" button on the right edge of the screen
   • Get a free API key from Google AI Studio
   • Paste your API key in the setup form

5. Configure Project Directories (optional)

   • Go to Settings tab → Scan Directories
   • Add custom directories to scan for git repos
   • Default: ~/Documents

Daily Workflow

• Check server status: View Docker containers with ps
• Deploy updates: git pull then docker-compose up -d
• Debug issues: Open SSH terminal or stream container logs
• Push local changes: Quick commit and push from Projects tab

Using the AI Assistant

Open the AI sidebar by clicking the "AI" button on the right edge of the screen. Then ask in natural language:

"List all my servers"
"What's running on production?"
"Run ./deploy.sh on staging"
"Docker compose restart on web-server"
"Git pull on production"

Permission Model:

• Read operations (listing servers, projects) execute automatically
• Commands (SSH, Docker, git) show what will run and require you to click "Approve"

This ensures you always have control over what actually executes on your servers.

Project Structure

src/
├── client/                 # React frontend
│   ├── components/
│   │   ├── ai/            # AI sidebar & chat components
│   │   ├── servers/       # Server management
│   │   ├── projects/      # Project management
│   │   ├── settings/      # Settings & scan directories
│   │   ├── terminal/      # SSH terminal
│   │   └── ui/            # Shared UI components
│   ├── hooks/              # Custom React hooks
│   └── styles/             # CSS modules
├── server/                 # Hono backend
│   ├── routes/             # API endpoints
│   ├── services/           # Business logic (including AI)
│   ├── schemas/            # Zod validation
│   └── websocket/          # Terminal & log streaming
└── shared/                 # Shared types

data/                       # JSON storage (gitignored)
├── servers.json
├── github.json
└── settings.json           # Scan dirs + encrypted Gemini key

API Endpoints

Method	Endpoint	Description
GET	/api/servers	List all servers
POST	/api/servers	Add new server
PUT	/api/servers/:id	Update server
DELETE	/api/servers/:id	Delete server
POST	/api/servers/:id/docker/:command	Run Docker command
GET	/api/servers/:id/services	List Docker services
POST	/api/servers/:id/git-pull	Git pull on server
WS	/ws/terminal/:serverId	SSH terminal session
WS	/ws/logs/:serverId	Docker log streaming
GET	/api/projects	List local git repos
POST	/api/projects/clone	Clone from GitHub
POST	/api/projects/:name/push	Push changes
GET	/api/ssh/keys	List SSH keys
POST	/api/ssh/generate	Generate new key
POST	/api/ssh/deploy/:serverId	Deploy key to server
GET	/api/settings	Get app settings
PUT	/api/settings	Update settings
POST	/api/settings/directories	Add scan directory
DELETE	/api/settings/directories	Remove scan directory
GET	/api/ai/config	Check AI configuration
PUT	/api/ai/config	Save Gemini API key
POST	/api/ai/chat	Send message to AI
POST	/api/ai/execute	Execute approved action

License

MIT License — feel free to use, modify, and share.

---

Made with by Umut Piynar