Home Assistant with VeilNet

Prerequisites

• Docker and Docker Compose installed
• VeilNet registration token
• Access to VeilNet Guardian service
• Home automation devices (optional, for initial setup)

Overview

This guide shows you how to deploy Home Assistant, an open-source home automation platform, with VeilNet for secure remote access. Home Assistant allows you to control and automate your smart home devices from a single interface.

With VeilNet, you can securely access your Home Assistant dashboard from anywhere without exposing it to the public internet.

Step 1: Create Docker Compose Configuration

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

services:
  veilnet-conflux:
    container_name: veilnet-conflux
    restart: unless-stopped
    env_file:
      - .env
    image: veilnet/conflux:beta
    pull_policy: always
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    network_mode: host

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    privileged: true
    volumes:
      - homeassistant:/config
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=<YOUR_TIMEZONE>
    network_mode: "container:veilnet-conflux"
    depends_on:
      - veilnet-conflux

volumes:
  homeassistant:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./homeassistant

Step 2: Create Environment File

Create a .env file in the same directory as your docker-compose.yml with the following variables:

VEILNET_REGISTRATION_TOKEN=<YOUR_REGISTRATION_TOKEN>
VEILNET_GUARDIAN=<YOUR_GUARDIAN_URL>
VEILNET_PORTAL=true
VEILNET_CONFLUX_TAG=<YOUR_CONFLUX_TAG>
VEILNET_CONFLUX_CIDR=<VEILNET_CIDR>

Replace the placeholders:

• <YOUR_REGISTRATION_TOKEN>: Your VeilNet registration token (obtained from the VeilNet portal)
• <YOUR_GUARDIAN_URL>: The URL of your VeilNet Guardian service (e.g., https://guardian.veilnet.app)
• <YOUR_CONFLUX_TAG>: A tag to identify this Conflux instance (e.g., home-automation)
• <VEILNET_CIDR>: Any IP address (e.g., 10.128.0.5/16) in CIDR format that belongs to the realm subnet (e.g., 10.128.0.0/16)

Step 3: Create Data Directories

Create the directory for persistent data storage:

mkdir -p homeassistant

This directory will store:

• homeassistant: Home Assistant configuration, database, and add-ons

Step 4: Deploy the Stack

Start all services:

docker-compose up -d

This will:

• Pull the Home Assistant and VeilNet Conflux images
• Start both containers
• Create persistent volume for data storage
• Automatically restart containers if they stop

Step 5: Verify Deployment

Check that all containers are running:

docker-compose ps

View the VeilNet Conflux logs to verify it's connecting:

docker logs veilnet-conflux -f

You should see logs indicating successful registration and connection to the VeilNet network.

Step 6: Initial Configuration

Local Access

1. Open http://localhost:8123 in your browser
2. Complete the Home Assistant setup wizard:
   • Create your administrator account
   • Set your location and timezone
   • Discover and configure your smart home devices
3. Start building your home automation dashboard

Remote Access via VeilNet

1. Find your host's VeilNet IP address:

ip addr show veilnet

Or check the VeilNet portal to see your assigned IP address.

2. Access Home Assistant from anywhere using http://<veilnet-ip>:8123 (e.g., http://10.128.0.5:8123)

Step 7: Access Your Home Assistant

Local Access

Once the service is running, you can access it locally:

• Web UI: http://localhost:8123

Remote Access via VeilNet

With VeilNet configured, you can access your Home Assistant dashboard remotely from anywhere in the world using the host's VeilNet IP address, as long as your device is also connected to the same VeilNet realm.

Access the web interface using:

• Web UI: http://<veilnet-ip>:8123 (e.g., http://10.128.0.5:8123)

Step 8: Configure Integrations

1. Log in to Home Assistant (locally or via VeilNet IP)
2. Go to Settings → Devices & Services
3. Click "Add Integration" to discover and add your smart home devices
4. Popular integrations include:
   • Zigbee/Z-Wave devices
   • Philips Hue
   • SmartThings
   • Google Nest

• Amazon Alexa
• MQTT devices

Updating Services

To update to newer versions:

docker-compose pull
docker-compose up -d

This will pull the latest images and restart the containers with updated versions.

Stopping and Removing

To stop all services:

docker-compose down

To remove containers and volumes (this will delete all data):

docker-compose down -v

Warning: Removing volumes will delete all Home Assistant configuration, automations, and device settings. Make sure to back up your configuration before removing volumes.

FAQ

Can I use Home Assistant mobile app with VeilNet?

Yes! The Home Assistant mobile app can connect to your instance using the VeilNet IP address. Configure the app to use http://<veilnet-ip>:8123 as the server URL.

How do I access Home Assistant when I'm away from home?

Once your device is connected to the same VeilNet realm, you can access Home Assistant using the host's VeilNet IP address from anywhere. No need for port forwarding or exposing your server to the internet. Since Home Assistant shares the network namespace with veilnet-conflux, it can also use the VeilNet TUN device for optimal network performance.

Can I share access with family members?

Yes! Add family members to the same VeilNet realm through the VeilNet portal. Once they're connected, they can access Home Assistant using the host's VeilNet IP address. Then create user accounts for them in Home Assistant's user management settings.

What about automations and scripts?

All your automations, scripts, and configurations are stored in the homeassistant directory and will persist across container restarts. You can edit them through the web interface or directly in the configuration files.

Can I use Zigbee/Z-Wave USB dongles?

Yes! Home Assistant needs privileged mode to access USB devices. The docker-compose.yml already includes privileged: true for this purpose. You may need to add device mappings for specific USB devices.

Why use NET_ADMIN capability for VeilNet instead of privileged mode?

The NET_ADMIN capability provides only the necessary permissions for VeilNet to create and manage network interfaces, without granting full privileged access. This is more secure while still allowing VeilNet to function properly. Home Assistant requires privileged mode for USB device access, but VeilNet doesn't need it.