Docker Installation

TOMMY can be run as a standalone Docker container for self-hosted setups and users who want to run TOMMY independently of Home Assistant.

Requirements

Linux host (Windows/macOS Docker not supported)
AMD64 or ARM64 architecture
Host networking for mDNS discovery
Docker installed and running

Linux Host Required

TOMMY Docker container requires a Linux host. Docker on Windows (including WSL2) and macOS are not supported due to networking requirements for mDNS device discovery.

Installation

Docker Compose (Recommended)

Docker Compose provides an easier way to manage TOMMY with a configuration file.

Quick Start:

Create a docker-compose.yml file with the following content:

services:
  tommy:
    image: tommysense/virtual-bridge:latest
    container_name: tommy
    network_mode: host
    restart: unless-stopped
    environment:
      DASHBOARD_PORT: 8089          # Web Dashboard
      FILE_SERVER_HTTP_PORT: 8090   # Configuration file and OTA
      FILE_SERVER_HTTPS_PORT: 8091  # Configuration file and OTA
      MQTT_PORT: 1886               # Built-in MQTT broker
      UDP_RELAY_PORT: 8547          # Device communication
    volumes:
      - ~/.tommy:/data

Start the container:

docker compose up -d

Stop the container:

docker compose down

Update TOMMY:

docker compose down && docker compose pull && docker compose up -d

Docker Run

Alternatively, you can run TOMMY directly with Docker:

docker run -d --name tommy \
  --network host \
  -v $HOME/.tommy:/data \
  -e DASHBOARD_PORT=8089 \
  -e FILE_SERVER_HTTP_PORT=8090 \
  -e FILE_SERVER_HTTPS_PORT=8091 \
  -e MQTT_PORT=1886 \
  -e UDP_RELAY_PORT=8547 \
  --restart unless-stopped \
  tommysense/virtual-bridge:latest

Configuration Options

You can customize TOMMY's behavior using environment variables:

Environment Variable	Default	Description
`DASHBOARD_PORT`	8089	Web dashboard
`FILE_SERVER_HTTP_PORT`	8090	Configuration file and OTA
`FILE_SERVER_HTTPS_PORT`	8091	Configuration file and OTA
`MQTT_PORT`	1886	Built-in MQTT broker
`UDP_RELAY_PORT`	8547	Device communication

Important Notes

Host Networking Requirement

TOMMY requires host networking (--network host or network_mode: host in docker-compose.yml) because devices use mDNS for auto-discovery, which requires host networking.

Data Persistence

The volume mount (-v $HOME/.tommy:/data or ~/.tommy:/data in docker-compose.yml) ensures configuration, zone settings, firmware files, and logs persist across container restarts.

Accessing the Dashboard

After starting the container, access the TOMMY dashboard at:

http://localhost:8089

Or replace localhost with your server's IP address if accessing remotely.

Managing the Container

View Logs

docker logs tommy

Stop the Container

docker stop tommy

Start the Container

docker start tommy

Update TOMMY

Using Docker Compose:

docker compose down && docker compose pull && docker compose up -d

Using Docker Run:

# Stop and remove the old container
docker stop tommy
docker rm tommy

# Pull the latest image
docker pull tommysense/virtual-bridge:latest

# Start with the same configuration
docker run -d --name tommy \
  --network host \
  -v $HOME/.tommy:/data \
  -e DASHBOARD_PORT=8089 \
  -e FILE_SERVER_HTTP_PORT=8090 \
  -e FILE_SERVER_HTTPS_PORT=8091 \
  -e MQTT_PORT=1886 \
  -e UDP_RELAY_PORT=8547 \
  --restart unless-stopped \
  tommysense/virtual-bridge:latest

Troubleshooting

Ensure you're running on a Linux host (not Windows/macOS Docker Desktop)
Check that --network host (or network_mode: host in docker-compose.yml) is specified
Verify no port conflicts with other services
Check container logs with docker logs tommy

Docker Installation

On this page