procboard

A minimal web dashboard for managing console applications on a Linux server. Register any app — Python bot, FastAPI service, whatever — and get a UI to start, stop, restart it and tail its logs. No changes to the managed app required.

![dashboard screenshot placeholder]

Features

• Start / stop / restart / force-kill processes
• Optional bot autostart when procboard itself starts
• Live uptime counter per app
• Inline log tail with auto-refresh (no page reload)
• Optional HTTP health checks
• Add and delete apps through the UI (no manual JSON editing)
• Auto-detect run command from project directory, including meta-agent
• File browser for picking paths in the add-bot form
• Dark mode

Requirements

• Python 3.10+
• Linux (uses pkill for force-kill)

Setup

git clone https://github.com/yourname/procboard
cd procboard

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

cp bots.json.example bots.json
# edit bots.json to add your apps (or use the web UI)

export PROCBOARD_PORT=18777
python -m app.main
# open http://localhost:18777

Configuration (bots.json)

{
  "my_bot": {
    "name": "My Bot",
    "cwd": "/home/user/my_bot",
    "cmd": "/home/user/my_bot/venv/bin/python -u app.py",
    "env_file": "/home/user/my_bot/.env",
    "url": null,
    "health_url": null,
    "autostart": true
  }
}

Field	Required	Description
name	yes	Display name shown in the dashboard
cwd	yes	Working directory for the process
cmd	yes	Shell command to start the app
env_file	no	Path to a .env file to inject into the process environment
url	no	URL shown as a clickable link when the app is running
health_url	no	HTTP endpoint polled for health status (must return < 400)
autostart	no	Start this app automatically when procboard starts

The JSON key (e.g. my_bot) is the internal ID. It's auto-generated from the display name when adding via UI.

Run Without Manual Clicks

To start bots automatically, set "autostart": true for the apps you want. Procboard will launch them during FastAPI startup.

For full unattended boot, run procboard itself under systemd:

[Unit]
Description=procboard
After=network.target

[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER/procboard
Environment="PATH=/home/YOUR_USER/procboard/venv/bin:/usr/bin:/bin"
Environment="PROCBOARD_PORT=18777"
ExecStart=/home/YOUR_USER/procboard/venv/bin/python -m app.main
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Example:

sudo cp procboard.service /etc/systemd/system/procboard.service
sudo systemctl daemon-reload
sudo systemctl enable --now procboard

With this setup, the server boots, procboard starts automatically, and every bot with "autostart": true is launched without opening the web panel.

The panel port is controlled by PROCBOARD_PORT. Default: 18777.

API

Endpoint	Description
GET /api/status	Live status JSON for all bots
GET /api/logs/{name}?lines=N	Last N log lines as JSON
GET /api/detect?cwd=PATH	Auto-detect run command from a project directory (meta-agent, Python/FastAPI)
GET /api/browse?path=PATH	Directory listing

License

MIT