Skip to content
OpenAVC Docs

Getting Started with OpenAVC

OpenAVC is an open-source control platform for AV spaces. Install it on a PC, mini PC, or server, open a browser, and start building. No proprietary processors or licenses required.

Choose Your Installation Method

Every installer, image, and command below is on the OpenAVC download page, which always points at the current release.

MethodBest ForTime
Windows InstallerAV rack PCs, mini PCs, laptops2 minutes
macOS InstallerMacs and Mac minis2 minutes
DockerServers, multi-room deployments2 minutes
Linux Install ScriptDedicated Linux machines3 minutes
Raspberry Pi ImagePi 4 or Pi 5, optionally driving a wall panel10 minutes
From SourceDevelopment, contributing5 minutes

All methods are functionally identical. Choose whatever fits your environment.

Windows Installer

The fastest way to get started on Windows.

  1. Download the installer (OpenAVC-Setup-x.x.x.exe) from the download page
  2. Run the installer and follow the prompts
  3. OpenAVC starts automatically as a Windows service

What the installer does:

  • Installs to C:\Program Files\OpenAVC
  • Stores project data in C:\ProgramData\OpenAVC, readable only by the OpenAVC service and administrators
  • Creates a Windows service (OpenAVC) that starts automatically on boot
  • Adds a system tray app for quick access to the web interface
  • Adds a Windows Firewall rule for the OpenAVC server
  • Creates Start Menu and optional Desktop shortcuts

After installation, open http://localhost:8080/programmer in your browser to start building.

OpenAVC accepts connections from tablets, phones and other computers on any network this PC is on. To limit that to one network, or to this computer only, change Accept connections from in Settings > Network.

macOS Installer

The fastest way to get started on a Mac.

  1. Download the .pkg from the download page. Choose Apple Silicon (M-series) or Intel to match your Mac
  2. Double-click it and follow the installer, entering your password once when asked
  3. OpenAVC starts automatically in the background

What the installer does:

  • Installs OpenAVC.app to /Applications
  • Stores project data in /Library/Application Support/OpenAVC
  • Runs the server as a background service (LaunchDaemon) that starts on boot
  • Adds a menu-bar app for quick access to the web interface and service controls
  • Opens the Programmer IDE in your browser when the install finishes

After installation, open http://localhost:8080/programmer in your browser to start building.

OpenAVC accepts connections from other devices on any network this Mac is on. To limit that, change Accept connections from in Settings > Network.

Docker

Linux Docker hosts only — see Deployment for the Docker Desktop limitation on Windows and Mac. Download the compose file and start it:

Terminal window
curl -fsSL https://raw.githubusercontent.com/open-avc/openavc/main/installer/docker-compose.yml -o docker-compose.yml
docker compose up -d

The compose file ships with network_mode: host and cap_add: NET_RAW so device discovery and mDNS can reach AV equipment on your LAN. Don’t strip those out — discovery won’t work without them.

The container accepts connections from any network the host is on (Docker says how to limit that). Access at http://<host-ip>:8080/programmer.

For serial/USB device passthrough, add devices: ["/dev/ttyUSB0:/dev/ttyUSB0"] to the compose file.

Linux Install Script

One command to install on any Linux machine:

Terminal window
curl -sSL https://get.openavc.com | sudo bash

This installs OpenAVC to /opt/openavc, creates a systemd service, and starts the server. Data is stored in /var/lib/openavc. The service starts automatically on boot.

The installer pulls in everything OpenAVC needs from your distro’s package manager: Python 3.11+, python3-venv, python3-pip, ca-certificates, and tar. On a desktop or standard server image these are usually already present. On minimal cloud or container images you may need curl (or wget) installed before you can run the command above:

Terminal window
# Debian/Ubuntu
sudo apt-get install -y curl ca-certificates


# Fedora/RHEL/Rocky
sudo dnf install -y curl ca-certificates


# Arch
sudo pacman -S curl ca-certificates

After installation:

Terminal window
sudo systemctl status openavc    # Check status
sudo journalctl -u openavc -f    # View logs

Access at http://localhost:8080/programmer, or http://<server-ip>:8080/programmer from another device. The installed service accepts connections from any network the machine is on, so tablets and panels can reach it.

The first time you open the Programmer, you choose an admin username (prefilled with admin) and password. They protect the Programmer and the control API, and you’ll enter both on the Programmer’s sign-in screen. A tablet or browser that opens the room panel at /panel waits until you approve it once in the Programmer; nobody enters a password on the panel. You can change them later in Settings > Access > Programmer login.

To accept connections from one network only, or from this machine only, change Accept connections from in Settings > Network.

Raspberry Pi Image

A ready-to-run SD card image for the Raspberry Pi 4 and Pi 5, with OpenAVC already installed and set to start on boot.

  1. Download the image from the download page
  2. Write it to an SD card with Raspberry Pi Imager
  3. Put the card in the Pi, connect a network cable, and power it on

The first boot takes an extra minute while OpenAVC sets itself up. With an HDMI display connected, the Pi shows its IP address and access URLs on screen. On networks with mDNS it is also reachable at http://openavc.local:8080/programmer.

Connect an HDMI touchscreen and the same Pi doubles as the room’s wall panel. For the full first-boot walkthrough, including the operating system login and SSH, see First Boot (Raspberry Pi Image) in the Deployment Guide.

Install from Source

For development or when you want full control over the installation.

Prerequisites

ToolWhat It DoesWhere to Get It
Python 3.11+Runs the OpenAVC serverpython.org/downloads
Node.js 22 or 24Builds the web interfacesnodejs.org
GitDownloads the OpenAVC source codegit-scm.com

When installing Python, check “Add Python to PATH” when prompted. For Node.js, the default installer settings are fine.

Download and Build

Open a terminal (PowerShell on Windows, Terminal on Mac/Linux).

Linux only. The Python installers for Windows and Mac bundle everything you need. On Debian/Ubuntu, Python is split across several packages, and minimal images often omit ca-certificates. Install the prerequisites first:

Terminal window
# Debian/Ubuntu
sudo apt-get install -y python3 python3-venv python3-pip git curl ca-certificates


# Fedora/RHEL/Rocky
sudo dnf install -y python3 python3-pip git curl ca-certificates


# Arch
sudo pacman -S python python-pip git curl ca-certificates

Node.js and npm are also required. Install Node.js 22 or 24 from your distro or nodejs.org.

Then clone and build:

Terminal window
git clone https://github.com/open-avc/openavc.git
cd openavc
python3 -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate
pip install -r requirements.txt
cd openavc/web/programmer && npm install && npm run build && cd ../../..
cd openavc/web/simulator && npm install && npm run build && cd ../../..

The virtual environment isolates OpenAVC’s Python dependencies from your system Python. On current Debian/Ubuntu, installing into the system Python is blocked by default (PEP 668), so the venv step isn’t optional.

Start the Server

With the venv still activated:

Terminal window
python -m openavc.main

This starts the OpenAVC server on port 8080, accepting connections from this computer only.

Access the Web Interface

Once OpenAVC is running, open a browser:

URLPurpose
http://localhost:8080/Landing page with links to the Programmer and touch panel
http://localhost:8080/programmerProgrammer IDE (where you build projects)
http://localhost:8080/panelEnd-user touch panel
http://localhost:8080/api/healthHealth check endpoint

First-time startup: When the server first starts, it initializes in the background. You may briefly see a loading page while the engine starts up. This only takes a few seconds.

HTTPS: OpenAVC ships with HTTPS off — the URLs above use plain HTTP because most deployments run on an isolated AV VLAN. Once you have things running, you can opt in to HTTPS from Settings > Security in the Programmer IDE. After enabling, the IDE is reachable at https://localhost:8443/programmer, and http://localhost:8080/... automatically redirects to the HTTPS URL. See the Deployment guide for the full enable flow.

First Steps: Explore the Demo

When you start OpenAVC for the first time, a set of starter projects are available in the Project Library.

Prefer to be taught? OpenAVC Academy covers this page and the Programmer in its Foundations course, with a guided exercise in the Simulator, and Associate then builds a complete space. Both run against simulated equipment, so you need nothing but the install you just did. If you would rather keep reading, carry on here and then build your first space.

1. Open the Programmer IDE

Navigate to http://localhost:8080/programmer in your browser.

2. Open a Starter Project

Click Program in the sidebar. At the bottom, you’ll see the Project Library with starter projects (Simple Projector, Conference Room, Classroom, Advanced AV Suite). Click Simple Projector and then Open to load it.

3. Explore the Sidebar

The sidebar has these sections:

  • Dashboard. System status overview with device grid, active triggers, monitored readings, and panel access URLs.
  • Program. Create, save, and manage projects. Import/export. Backups.
  • Devices. Connected equipment, driver library, device groups, and network discovery.
  • State. Variables, device states, and activity feed.
  • UI Builder. Visual drag-and-drop panel designer.
  • Macros. Sequence-based automation with triggers.
  • Code. Python scripting and driver editing with Monaco editor.
  • Plugins. Install and configure system plugins.
  • Inter-System. Communication between OpenAVC instances.
  • AI Assistant. AI-powered help and automation (requires cloud connection).
  • Cloud. Cloud platform connection and monitoring.
  • Log. Real-time system log and state changes.
  • Settings. Server configuration (port, who can connect, logging).
  • Updates. Check for and install OpenAVC updates.

At the bottom of the sidebar, the Simulate Devices button (play icon) starts the device simulator so you can test without real hardware.

4. Start the Simulator

Click the play button at the bottom of the sidebar. This starts virtual devices that respond to commands just like real hardware. The Simulator UI opens in a new browser tab where you can interact with the virtual devices from the “hardware side.”

5. Check Device State

Click Devices in the sidebar. You’ll see the devices from the starter project. With the simulator running, they should connect automatically and show green indicators. Click a device to see its live state (power, input, lamp hours) and test commands.

6. Test a Command

In the Device View, select the projector and use the command testing panel. Choose “power_on” and click Send. Watch the state update in real-time.

7. Open the Panel UI

Navigate to http://localhost:8080/panel in another tab. This is what end users see on a touchscreen. Press the buttons and watch commands flow through the system.

Accessing from a tablet or phone: The packaged installs (Windows Installer, macOS Installer, Docker, the Linux Install Script, and the Raspberry Pi image) accept connections from any network, so the panel URL works from any device on the same network. An install from source starts at This computer only. To open it up on a source install:

  1. Go to Settings > Network in the Programmer IDE
  2. Set Accept connections from to Any network, or to the adapter on the tablet’s network
  3. Save, then click Restart now
  4. The Dashboard will show the panel URL with your machine’s IP address (e.g., http://192.168.1.100:8080/panel) that you can open on any device on the same network
  5. Open it on the tablet. The panel shows Waiting for approval with a six-digit code; approve it from the notice that appears in the Programmer, or from the Dashboard’s Panels list, and the panel loads. Approve each device once; it stays approved.

Environment Variables

These environment variables override the corresponding system.json settings, and the matching field in Settings shows locked. Useful for Docker, systemd, and scripted deployments.

VariableDefaultDescription
OPENAVC_PORT8080HTTP server port
OPENAVC_BIND(none)Who can connect, in place of Settings > Network > Accept connections from: 0.0.0.0 any network, 127.0.0.1 this computer only, or one of this computer’s addresses
OPENAVC_PROGRAMMER_PASSWORD(none)Password for Programmer IDE access
OPENAVC_API_KEY(none)API key for REST/WebSocket integrations
OPENAVC_LOG_LEVELinfoLog level (debug, info, warning, error)
OPENAVC_DATA_DIR(platform default)Override data directory location
OPENAVC_LOG_DIR(platform default)Override log directory location

See the Deployment Guide for the full configuration reference.

Next Steps