Kiosk Mode

Kiosk mode enables Liveposter to run in fullscreen without browser UI elements, making it perfect for digital signage, smart displays, interactive kiosks, and unattended installations.

What is Kiosk Mode?

Kiosk mode launches a web browser in fullscreen without:

• Address bar
• Tabs
• Bookmarks bar
• Navigation buttons
• Browser menus

This creates an immersive, distraction-free display ideal for public installations, digital signage, retail displays, and anywhere you need professional presentation without browser chrome.

Why Use Kiosk Mode?

Digital Signage: Display dynamic content in stores, lobbies, or public spaces without any browser UI distractions.

Smart Displays: Transform any screen with a browser into a dedicated display device.

Interactive Kiosks: Create touch-enabled displays for museums, exhibitions, or retail environments.

Trade Shows & Events: Professional presentations without visible browser elements.

Retail Displays: Product showcases that look polished and purpose-built.

Lobby Screens: Welcome displays and information boards that appear as dedicated hardware.

Quick Start

The easiest way to run Liveposter in kiosk mode is using the built-in kiosk command:

# Run default demo in kiosk mode
npx liveposter kiosk

# Run specific poster in kiosk mode
npx liveposter kiosk path/to/your-poster.json

# Run poster list in kiosk mode
npx liveposter kiosk path/to/poster-list.json

This single command:

1. Automatically kills any process using port 3000
2. Starts the Liveposter server
3. Waits for the server to be ready
4. Launches Chrome in fullscreen kiosk mode
5. Works cross-platform (Windows, macOS, Linux)

Platform-Specific Instructions

macOS

Using Chrome

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --kiosk \
  --app=http://localhost:3000

Additional Options

# Disable pinch gestures and navigation
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --kiosk \
  --app=http://localhost:3000 \
  --disable-pinch \
  --overscroll-history-navigation=0 \
  --disable-features=TranslateUI

Using Safari (Limited Kiosk Features)

Safari doesn’t have a true kiosk mode, but you can approximate it:

# Open in fullscreen (then press Cmd+Shift+F)
open -a Safari http://localhost:3000

For better Safari kiosk mode, consider third-party tools like FullScreen.

Windows

Using Chrome

chrome --kiosk --app=http://localhost:3000

Or with full path:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --kiosk --app=http://localhost:3000

Using Edge

msedge --kiosk --app=http://localhost:3000

Additional Options

# Disable gestures and prevent closing
chrome --kiosk --app=http://localhost:3000 ^
  --disable-pinch ^
  --overscroll-history-navigation=0 ^
  --disable-features=Translate ^
  --no-first-run

PowerShell Script

Create launch-kiosk.ps1:

# Kill any process on port 3000
$processes = netstat -ano | findstr :3000 | ForEach-Object {
    $_ -match '\s+(\d+)$' | Out-Null
    $matches[1]
} | Select-Object -Unique

foreach ($pid in $processes) {
    if ($pid) {
        Stop-Process -Id $pid -Force -ErrorAction SilentlyContinue
    }
}

# Start Liveposter server in background
Start-Process -NoNewWindow -FilePath "npx" -ArgumentList "liveposter", "path/to/poster.json"

# Wait for server to be ready
Start-Sleep -Seconds 3

# Launch Chrome in kiosk mode
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --kiosk --app=http://localhost:3000

Linux

Using Chromium

chromium-browser --kiosk --app=http://localhost:3000

Using Google Chrome

google-chrome --kiosk --app=http://localhost:3000

Additional Options

# Full kiosk setup with gesture disabling
chromium-browser --kiosk --app=http://localhost:3000 \
  --disable-pinch \
  --overscroll-history-navigation=0 \
  --disable-features=TranslateUI \
  --no-first-run \
  --disable-infobars \
  --disable-session-crashed-bubble

Preventing Exit (for Public Kiosks)

For truly locked-down kiosks, you may want to prevent users from exiting:

# Launch in a separate X session (requires xserver-xorg-video-dummy)
xinit /path/to/kiosk-script.sh -- :1

Browser Options Reference

Essential Kiosk Flags

Flag	Purpose
--kiosk	Launches browser in fullscreen kiosk mode
--app=URL	Opens URL as an application window (no tabs)

Recommended Additional Flags

Flag	Purpose
--disable-pinch	Disables pinch-to-zoom gestures
--overscroll-history-navigation=0	Disables swipe navigation
--disable-features=TranslateUI	Disables translation prompts
--no-first-run	Skips first-run dialogs
--disable-infobars	Removes info bars
--disable-session-crashed-bubble	Removes crash recovery dialogs
--disable-restore-session-state	Prevents session restore

Advanced Flags

Flag	Purpose
--incognito	Private mode (no history/cookies)
--start-fullscreen	Alternative to —kiosk (allows tabs)
--disable-extensions	Disables all extensions
--noerrdialogs	Suppresses error dialogs
--disable-component-update	Prevents component updates

Example Full Configuration

chromium-browser \
  --kiosk \
  --app=http://localhost:3000 \
  --disable-pinch \
  --overscroll-history-navigation=0 \
  --disable-features=TranslateUI \
  --no-first-run \
  --disable-infobars \
  --disable-session-crashed-bubble \
  --disable-restore-session-state \
  --incognito \
  --noerrdialogs

Auto-Start on Boot

Windows

Method 1: Startup Folder

1. Press Win + R, type shell:startup, press Enter
2. Create a shortcut to your launch script
3. The script will run automatically on login

Create startup-liveposter.bat:

@echo off
cd C:\path\to\your\poster
start /B npx liveposter kiosk poster.json

Method 2: Task Scheduler

1. Open Task Scheduler
2. Create Basic Task
3. Trigger: “When I log on”
4. Action: “Start a program”
5. Program: cmd.exe
6. Arguments: /c "cd C:\path\to\poster && npx liveposter kiosk poster.json"

macOS

Using Launch Agent

Create ~/Library/LaunchAgents/com.liveposter.kiosk.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.liveposter.kiosk</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/npx</string>
        <string>liveposter</string>
        <string>kiosk</string>
        <string>/path/to/your/poster.json</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/path/to/poster/directory</string>
</dict>
</plist>

Load the agent:

launchctl load ~/Library/LaunchAgents/com.liveposter.kiosk.plist

Using Login Items

1. System Preferences → Users & Groups
2. Select your user → Login Items
3. Click + and add your launch script

Linux (systemd)

System-Wide Service

Create /etc/systemd/system/liveposter-kiosk.service:

[Unit]
Description=Liveposter Kiosk Display
After=graphical.target network.target

[Service]
Type=simple
User=displayuser
Environment=DISPLAY=:0
Environment=XAUTHORITY=/home/displayuser/.Xauthority
WorkingDirectory=/home/displayuser/liveposter
ExecStart=/usr/bin/npx liveposter kiosk /home/displayuser/liveposter/poster.json
Restart=always
RestartSec=10

[Install]
WantedBy=graphical.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable liveposter-kiosk
sudo systemctl start liveposter-kiosk

Check status:

sudo systemctl status liveposter-kiosk

View logs:

sudo journalctl -u liveposter-kiosk -f

User Service (Per-User)

Create ~/.config/systemd/user/liveposter-kiosk.service:

[Unit]
Description=Liveposter Kiosk Display
After=graphical-session.target

[Service]
Type=simple
WorkingDirectory=%h/liveposter
ExecStart=/usr/bin/npx liveposter kiosk %h/liveposter/poster.json
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable liveposter-kiosk
systemctl --user start liveposter-kiosk

Linux (Desktop Entry)

Create ~/.config/autostart/liveposter-kiosk.desktop:

[Desktop Entry]
Type=Application
Name=Liveposter Kiosk
Exec=/usr/bin/npx liveposter kiosk /home/user/liveposter/poster.json
Terminal=false
X-GNOME-Autostart-enabled=true

Development Workflow

Testing Kiosk Mode

During development, you may not want full kiosk mode. Use development mode instead:

# Hot-reload development mode
npx liveposter dev path/to/poster.json

# Then test kiosk mode when ready
npx liveposter kiosk path/to/poster.json

Quick Iteration

For rapid testing:

1. Keep npx liveposter dev poster.json running
2. Edit poster.json (changes auto-reload)
3. When satisfied, test with npx liveposter kiosk poster.json

Script-Based Workflow

Create dev.sh for development:

#!/bin/bash
npx liveposter dev poster.json

Create kiosk.sh for testing kiosk mode:

#!/bin/bash
npx liveposter kiosk poster.json

Troubleshooting

Browser Won’t Launch in Kiosk Mode

Issue: Chrome launches but not in kiosk mode

Solutions:

• Ensure no Chrome instances are already running (close all Chrome windows)
• Try adding --new-window flag
• Check Chrome installation path is correct
• Try --start-fullscreen instead of --kiosk

Check Chrome path:

# macOS
ls -la /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome

# Linux
which chromium-browser
which google-chrome

# Windows (PowerShell)
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"

Port Already in Use

Issue: “Port 3000 is already in use”

Solutions:

macOS/Linux:

# Find process using port 3000
lsof -ti:3000

# Kill the process
lsof -ti:3000 | xargs kill -9

Windows:

# Find process
netstat -ano | findstr :3000

# Kill process (replace PID with actual process ID)
taskkill /PID <PID> /F

The npx liveposter kiosk command handles this automatically.

Server Not Starting

Issue: Server fails to start

Solutions:

• Check Node.js is installed: node --version
• Ensure port 3000 is available
• Try a different port: PORT=3001 npx liveposter kiosk poster.json
• Check file paths are correct
• Review poster.json for syntax errors

Browser Exits Immediately

Issue: Kiosk browser opens then closes

Solutions:

• Server may not be ready yet; add delay before launching browser
• Check server is actually running: curl http://localhost:3000
• Try accessing URL manually first
• Check for browser crashes in logs

Cannot Exit Kiosk Mode

Issue: Stuck in fullscreen kiosk mode

Solutions:

• Press Alt + F4 (Windows/Linux) or Cmd + Q (macOS)
• Press F11 to exit fullscreen
• Ctrl + Alt + T (Linux) to open terminal
• Switch to another virtual terminal: Ctrl + Alt + F1-F6 (Linux)
• Use Task Manager (Windows) or Activity Monitor (macOS) to force quit

Display Issues

Issue: Content appears stretched or misaligned

Solutions:

• Check display resolution settings
• Ensure poster dimensions match display
• Use CSS to constrain container size
• Test with simpler poster first
• Check browser zoom is at 100%

Performance Issues

Issue: Animations are choppy or laggy

Solutions:

• Optimize image sizes (compress large images)
• Use WebP or JPEG instead of PNG for photos
• Reduce transition speeds
• Lower image resolution for large displays
• Close other applications
• Check GPU acceleration is enabled in browser

Auto-Start Not Working

Issue: Kiosk doesn’t launch on boot

Solutions:

Windows:

• Check startup script is in startup folder
• Verify script paths are absolute, not relative
• Check Task Scheduler task is enabled
• Look for errors in Task Scheduler history

macOS:

• Verify LaunchAgent plist syntax: plutil -lint file.plist
• Check launchd logs: log show --predicate 'subsystem == "com.apple.launchd"' --last 1h
• Ensure paths in plist are absolute
• Check file permissions

Linux:

• Check service status: systemctl status liveposter-kiosk
• View logs: journalctl -u liveposter-kiosk -n 50
• Ensure service is enabled: systemctl is-enabled liveposter-kiosk
• Verify user has display access (DISPLAY and XAUTHORITY)

Best Practices

Security Considerations

Public Kiosks:

• Use --incognito flag to prevent data persistence
• Disable navigation gestures
• Use separate user account with limited permissions
• Consider physical security (locked case, mounted display)

Network Access:

• Use local images when possible
• Cache external resources
• Consider offline-first approach
• Use HTTPS for remote resources

Reliability

Automatic Recovery:

• Enable auto-restart on crash (systemd Restart=always)
• Use process monitoring (PM2, systemd)
• Monitor server health
• Log errors for debugging

Resource Management:

• Monitor memory usage
• Restart periodically (daily cron job)
• Clean up temporary files
• Keep system updated

Content Management

Remote Updates:

• Use network-accessible JSON files
• Implement hot-reload for content changes
• Version your poster specifications
• Keep backups of working configurations

Testing:

• Test on target hardware before deployment
• Verify all images load correctly
• Check timing feels right on actual display
• Test auto-start functionality

Advanced Configurations

Multi-Display Setup

Run different posters on multiple displays:

# Display 1
DISPLAY=:0 npx liveposter kiosk poster1.json &

# Display 2
DISPLAY=:1 npx liveposter kiosk poster2.json &

Use different ports:

# Display 1 on port 3000
PORT=3000 npx liveposter kiosk poster1.json &

# Display 2 on port 3001
PORT=3001 npx liveposter kiosk poster2.json &

Remote Management

Use SSH to manage remote displays:

# SSH into display device
ssh user@display-device

# Check status
systemctl status liveposter-kiosk

# Restart
systemctl restart liveposter-kiosk

# Update content
cd ~/liveposter
git pull
systemctl restart liveposter-kiosk

Monitoring

Set up basic monitoring:

monitor-kiosk.sh

#!/bin/bash
while true; do
    if ! curl -s http://localhost:3000 > /dev/null; then
        echo "Server down, restarting..."
        systemctl restart liveposter-kiosk
    fi
    sleep 60
done

Run as cron job:

# Add to crontab
* * * * * /path/to/monitor-kiosk.sh

Platform-Specific Hardware

Raspberry Pi

For Raspberry Pi deployments, see the dedicated Raspberry Pi Setup Guide which covers:

• OS installation and configuration
• Performance optimization
• GPIO integration
• Power management
• Troubleshooting

Digital Signage Hardware

Recommended Specs:

• CPU: Dual-core 1.5GHz+
• RAM: 2GB+ (4GB recommended)
• Storage: 8GB+ SD/SSD
• GPU: Hardware video decode
• Display: HDMI output

Tested Platforms:

• Raspberry Pi 3/4/5
• Intel NUC
• Generic x86/x64 PCs
• Android TV boxes (with browser support)

Next Steps

• Review animation modes to design your kiosk content
• Explore configuration options for customization
• Check out examples for inspiration
• See Raspberry Pi guide for dedicated hardware setup

Additional Resources

• Chrome command-line switches: chromium.org/developers/how-tos/run-chromium-with-flags
• Systemd service examples: systemd documentation
• Digital signage best practices: Liveposter examples