Running ScreenerBot

Complete guide to running ScreenerBot: use the desktop application for everyday trading, and reserve the headless command-line build for VPS deployments or debugging.

Runtime Modes

ScreenerBot supports two runtime modes. The mode is automatically detected based on how you launch the bot:

GUI Mode (Desktop Application)

Native desktop window with embedded dashboard interface

Best For: macOS, Windows, Linux desktop users
Application Bundles: .app (macOS), .exe (Windows), installed package (Linux)
Auto-Detection: Automatically used when running from app bundle
Dashboard: Opens automatically in native window
Logs: Visible in console/terminal output

Headless Mode (Web Server)

Runs as a headless web server serving the full dashboard interface on port 8080. Access via browser from any device on your network — no GUI window, but complete web-based control.

Best For: VPS, dedicated servers, remote deployments where you access via browser
Desktop Use: Not recommended for daily trading on laptops/desktops—use GUI instead
Deployment: Single screenerbot binary runs as web server
Default Mode: Automatically used when running from command line
Dashboard: Access via browser at http://localhost:8080
Logs: Terminal output + daily log files in logs/

Mode Detection: The bot automatically detects if it's running from an application bundle (*.app, *.exe, or installed Linux package) and switches to GUI mode. Otherwise, it runs in headless mode as a web server on port 8080, providing full dashboard access via browser.

Recommendation: Run the desktop app on macOS/Windows/Linux for day-to-day trading. Use headless mode only for VPS/server deployments where you'll access the dashboard remotely via browser, or when you need verbose terminal logs for debugging.

Desktop Application (GUI Mode)

The desktop application provides the easiest way to run ScreenerBot on your local machine with a native window interface.

macOS

Starting ScreenerBot:

Open ScreenerBot.app from your Applications folder
Or double-click the app icon in Finder
The native window opens with the dashboard loaded
Wait 15-20 seconds for full initialization

First Launch - Gatekeeper:

macOS may show a security warning on first launch since the app is not notarized. To allow:

Right-click ScreenerBot.app → Open
Click "Open" in the dialog
Or: System Settings → Privacy & Security → Click "Open Anyway"

Viewing Logs:

Launch from Terminal to see console output:

open -a ScreenerBot

Or view log files in:

~/Library/Application Support/ScreenerBot/logs/

Windows

Starting ScreenerBot:

Launch ScreenerBot.exe from Start Menu or Desktop shortcut
Or double-click the .exe file
The application window opens with the dashboard
Wait 15-20 seconds for full initialization

First Launch - Windows Defender:

Windows SmartScreen may show a warning on first launch. To allow:

Click "More info" in the SmartScreen dialog
Click "Run anyway"

Viewing Logs:

Log files are automatically saved in:

%LOCALAPPDATA%\ScreenerBot\logs\

Linux Desktop

Starting ScreenerBot:

Install the DEB or RPM package (see Installation Guide)
Launch from your application menu, or run from terminal:

screenerbot

The application window opens with the dashboard
Wait 15-20 seconds for full initialization

Viewing Logs:

Log files are automatically saved in:

$XDG_DATA_HOME/ScreenerBot/logs/(fallback: ~/.local/share/ScreenerBot/logs/)

Headless Web Server Mode

In headless mode, ScreenerBot runs as a web server (no GUI window) serving the full dashboard interface on port 8080. Ideal for VPS and server deployments where you access the dashboard remotely from any device via web browser.

Local Headless Testing

Run ScreenerBot in headless mode on your local machine to see live terminal logs while accessing the dashboard via browser at localhost:8080. Use this for debugging and troubleshooting; for day-to-day trading on desktop, prefer the GUI application.

Starting (Foreground):

./screenerbot

Logs will appear directly in your terminal. The bot runs until you press Ctrl+C to stop.

Accessing Dashboard:

Open your web browser and navigate to:

http://localhost:8080

Wait 15-20 seconds after startup for full initialization. The port and host are configurable in the[webserver] section of config.toml.

Stopping:

Press Ctrl+C in the terminal to gracefully shut down the bot.

Linux VPS Deployment (Production Web Server)

Deploy ScreenerBot as a headless web server on your VPS for 24/7 automated trading. The bot runs in the background serving the full dashboard interface on port 8080, accessible via browser from anywhere. Use systemd to ensure automatic restarts and persistent operation.

Prerequisites:

Ubuntu 20.04+ / Debian 11+ / Fedora 34+ (GLIBC 2.29+)
Minimum: 4 CPU cores, 4GB RAM, 5GB storage
Root or sudo access
Completed initial setup (config.toml with wallet and RPC)

Important: 4 CPU cores and 4GB RAM are required for stable operation. Lower specs may cause performance issues or crashes. See System Requirements for recommended specs (8 cores, 8GB RAM).

Step 1: Download & Extract Headless Binary

Download and extract the ScreenerBot headless binary. Use a dedicated directory like /opt/screenerbot to avoid permission issues.

# Create dedicated directory (recommended)
sudo mkdir -p /opt/screenerbot
cd /opt/screenerbot

# Download (get direct link from https://screenerbot.io/download)
# Copy the "Linux Headless" download link for your architecture (x64 or ARM64)
curl -L "<DIRECT_LINK_FROM_DOWNLOAD_PAGE>" -o screenerbot.tar.gz

# Extract the tarball
tar -xzf screenerbot.tar.gz

# Make binary executable
chmod +x screenerbot

# Create symlink for system-wide access
sudo ln -s /opt/screenerbot/screenerbot /usr/local/bin/screenerbot

# Clean up tarball
rm screenerbot.tar.gz

# Verify installation
screenerbot --help

Why /opt/screenerbot? Using a dedicated directory keeps your system organized and avoids permission issues with home directories.

Alternative locations: You can also use /usr/local/screenerbot or ~/screenerbot. Just update the systemd service paths accordingly.

Step 2: Create Systemd Service for Web Server

Create a systemd service file to run ScreenerBot as a background web server. The service will automatically start on boot and restart if it crashes, ensuring 24/7 availability of your dashboard.

# Create service file
sudo nano /etc/systemd/system/screenerbot.service

Add the following configuration (adjust paths and username):

[Unit]
Description=ScreenerBot - Automated Solana Trading Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=your-username
Group=your-username
WorkingDirectory=/home/your-username
ExecStart=/usr/local/bin/screenerbot
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
PrivateTmp=true

# Environment
Environment="HOME=/home/your-username"

[Install]
WantedBy=multi-user.target

Important: Replace your-username with your actual Linux username. The WorkingDirectory should point to where your data/config.toml is located.

Step 3: Enable and Start Service

# Reload systemd to read new service file
sudo systemctl daemon-reload

# Enable service to start on boot
sudo systemctl enable screenerbot

# Start the service
sudo systemctl start screenerbot

# Check status
sudo systemctl status screenerbot

Step 4: Verify and Monitor

# View live logs
sudo journalctl -u screenerbot -f

# View recent logs
sudo journalctl -u screenerbot -n 100

# Check if running
sudo systemctl status screenerbot

# Check process
ps aux | grep screenerbot

Managing the Service:

# Stop the bot
sudo systemctl stop screenerbot

# Restart the bot
sudo systemctl restart screenerbot

# Disable auto-start on boot
sudo systemctl disable screenerbot

# Re-enable auto-start on boot
sudo systemctl enable screenerbot

Accessing Your Dashboard:

Once the service is running, ScreenerBot serves the full dashboard interface as a web application. You have two secure options for accessing it remotely:

Option A: SSH Tunnel (Recommended - Secure)

Access the web dashboard securely through an encrypted SSH tunnel. This keeps the web server bound to localhost while allowing you to use it from your local browser.

# From your local machine, create SSH tunnel
ssh -L 8080:localhost:8080 your-username@your-server-ip

# Keep the SSH connection open, then open in your browser:
# http://localhost:8080

Config stays default: host = "127.0.0.1". All traffic is encrypted via SSH. Dashboard appears as if running locally.

Option B: Direct Network Access (Configure Firewall!)

Expose the web server to your network by binding to all interfaces. Only use this if you understand firewall configuration and IP whitelisting.

Edit [webserver] section in data/config.toml:

[webserver]
host = "0.0.0.0"  # Bind to all network interfaces
port = 8080       # Or any port you prefer

Access at http://your-server-ip:8080 from any device on your network. Must configure firewall to restrict access by IP or use VPN!

Security Best Practice: The SSH tunnel (Option A) is the safest approach. It keeps the web server bound to localhost while providing secure encrypted access through SSH. Direct network binding (Option B) exposes the dashboard to anyone who can reach your server's IP address—only use with proper firewall rules.

Single Instance Protection

Cannot Run Multiple Instances

ScreenerBot uses a process lock file to prevent multiple instances from running simultaneously. This is critical for preventing:

Database Corruption: Multiple processes writing to same SQLite databases
Duplicate Trades: Multiple bots executing the same trades
Port Conflicts: Both trying to use port 8080 for webserver
Wallet Key Conflicts: Multiple processes using same private key. Important: Do not use the same wallet on different systems simultaneously. This will corrupt transaction verification, monitoring, and position management.

Lock File Location:

macOS:~/Library/Application Support/ScreenerBot/data/.screenerbot.lock

Windows:%LOCALAPPDATA%\ScreenerBot\data\.screenerbot.lock

Linux:$XDG_DATA_HOME/ScreenerBot/data/.screenerbot.lock(fallback: ~/.local/share/ScreenerBot/data/.screenerbot.lock)

Automatic Cleanup: The lock file is automatically removed when the bot stops gracefully. If the process crashes, the operating system automatically releases the lock.

Stopping ScreenerBot

Desktop Application

macOS: Cmd+Q or ScreenerBot → Quit
Windows: Alt+F4 or close window
Linux: Close window or Ctrl+C in terminal

All methods trigger graceful shutdown: open positions are preserved, databases are closed properly.

Command Line

Foreground (Terminal): Ctrl+C
Systemd Service: sudo systemctl stop screenerbot
Find & Kill Process: ps aux | grep screenerbot | grep -v grep

Graceful Shutdown: All stop methods trigger graceful shutdown. The bot will: complete pending operations, close database connections, save state, and release the process lock.

Troubleshooting

Error: "Another instance is already running"

This error means ScreenerBot is already running, or a stale lock file exists from a crash.

Solution 1: Stop Running Instance

# Find running process
ps aux | grep screenerbot | grep -v grep

# Stop it
pkill -f screenerbot

# Verify stopped
ps aux | grep screenerbot | grep -v grep

Solution 2: Remove Stale Lock (If No Process Found)

# macOS
rm "$HOME/Library/Application Support/ScreenerBot/data/.screenerbot.lock"

# Linux
rm "$XDG_DATA_HOME/ScreenerBot/data/.screenerbot.lock" 2>/dev/null || rm "$HOME/.local/share/ScreenerBot/data/.screenerbot.lock"

# Windows
del "%LOCALAPPDATA%\ScreenerBot\data\.screenerbot.lock"

Warning: Only remove the lock file if you're certain no instance is running.

Error: "Port 8080 already in use"

Another application is using port 8080, or ScreenerBot didn't shut down properly.

Find What's Using Port 8080:

# macOS/Linux
lsof -i :8080

# Windows
netstat -ano | findstr :8080

Change Webserver Port:

Edit config.toml and change the webserver port under [webserver] section. Or use the Dashboard Configuration page.

Can't Access Dashboard

Wait for Initialization: Dashboard needs 15-20 seconds to fully load after startup
Check Logs: Look for "Webserver started on http://localhost:8080" message
Verify URL: Must be http://localhost:8080 (not https)
Firewall: Ensure firewall isn't blocking port 8080

Getting Started

Dashboard Guides

Trading Guides

Reference

Trading Tools

Need Help?

Running ScreenerBot

Runtime Modes

GUI Mode (Desktop Application)

Headless Mode (Web Server)

Desktop Application (GUI Mode)

macOS

Starting ScreenerBot:

First Launch - Gatekeeper:

Viewing Logs:

Windows

Starting ScreenerBot:

First Launch - Windows Defender:

Viewing Logs:

Linux Desktop

Starting ScreenerBot:

Viewing Logs:

Headless Web Server Mode

Local Headless Testing

Starting (Foreground):

Accessing Dashboard:

Stopping:

Linux VPS Deployment (Production Web Server)

Prerequisites:

Step 1: Download & Extract Headless Binary

Step 2: Create Systemd Service for Web Server

Step 3: Enable and Start Service

Step 4: Verify and Monitor

Managing the Service:

Accessing Your Dashboard:

Single Instance Protection

Cannot Run Multiple Instances

Stopping ScreenerBot

Desktop Application

Command Line

Troubleshooting

Error: "Another instance is already running"

Solution 1: Stop Running Instance

Solution 2: Remove Stale Lock (If No Process Found)

Error: "Port 8080 already in use"

Find What's Using Port 8080:

Change Webserver Port:

Can't Access Dashboard

Related Topics