Companion Voice

For the Home Assistant Voice PE

Companion Voice for Home Assistant: your voice assistant, your Companion.

Say the wake word and get an answer from a Companion that runs on your own computer, knows your life from Companion Memory, and in the recommended setup keeps every word inside your home.

Set it up How it works
  • Guided setupbuilt in your browser, step by step
  • Runs locallyon a Mac, PC or Linux box
  • Keeps your setupworks with the Home Assistant you have
Talks to Home Assistant over Wyoming, TCP 10700

Don't have a Companion yet?

Get a Companion Core, a personal AI appliance and local server, or download Companion Hub to turn a computer you already own into one.

Buy Companion Core Download Companion

How it works

Three hops, by default all inside your home

  1. 1

    You speak

    The Voice PE hears its wake word on the device and streams your question to Home Assistant.

  2. 2

    Home Assistant listens

    Its Assist pipeline turns speech into text and hands it to the Companion voice bridge over Wyoming.

  3. 3

    Your Companion answers

    Your local model answers with what Companion Memory knows about you, and the reply is spoken back.

Keep Home Assistant's own Whisper and Piper for speech, or let Companion handle speech too. Nothing leaves the house unless you choose it: cloud speech sends audio to OpenAI, and a model tag that starts with openai: sends your questions, and the memory an answer draws on, to OpenAI.

Guided setup

Set it up

Everything below is built in your browser. Keys are generated here and are never sent to us. Prefer to read first? Read the full guide.

0 of 7 done

  1. Choose your setup

    Its address on your network. Used to fill in the steps below.

    More options

    Comma-separated codes, for example en,de.

  2. Connect Companion Memory Optional

    With memory connected, answers draw on what your Companion knows about you, and each exchange is saved as a conversation.

  3. Download your two files

    Put both in one empty folder on that computer, for example companion-voice.

    Look inside .env
    .env 
    
              
    
            
    
            
    If the download arrives as env.txt or _env, rename it to .env. The keys are made when this page loads, so download once and keep that file: reloading the page makes new keys that will not match a stack you already started.
    
          
    4. 

          
          
  4. 
            
    
              
    Start it
    
              
            
    
            
    Open a terminal in that folder and run:
    
            
    
              
    
                terminal
                
    
              
    
              
    
            
    
            
    The first start downloads the model, which can take a few minutes.
    
          
    5. 

          
          
  5. 
            
    
              
    Install from the Hub store
    
              
            
    
            
    New to Companion Hub? Download Companion first, then come back here.
    
            
    Open your Companion Hub, find Home Assistant Voice in the store (that is the name it has there) and install it. Hub connects it to the models it already runs.
    
            
    
              View in the Hub store
            
    
            
    The listing is available now and needs Companion Hub 0.2.41 or newer. If you do not see it, check your Hub version, or choose Docker above.
    
          
    6. 

          
          
  6. 
            
    
              
    Approve Companion Memory
    
              
            
    
            
    Hub asks you to approve a key for the app. It can only reach your memory, to recall and to save conversations. It cannot delete anything.
    
          
    7. 

          
          
  7. 
            
    
              
    Add it to Home Assistant
    
              
            
    
            
    Add the Wyoming Protocol integration and enter:
    
            
    
              
              
            
    
            
    
              Open Home Assistant
            
    
            
    Home Assistant then shows three services: companion-stt, companion-tts and companion-conversation.
    
          
    8. 

          
          
  8. 
            
    
              
    Give the Voice PE its assistant
    
              
            
    
            
    In Voice assistants, add an assistant called Companion with these choices, then pick it on the Voice PE's device page.
    
            
    
              
    
                
    SettingChoose
    
                
              
    
            
    
            
    
              Open Voice assistants
              Open Devices
            
    
          
    9. 

          
          
  9. 
            
    
              
    Check it
    
              
            
    
            
    Run these two lines from any computer on your network. The first shows that ci-server is up, the second shows what it is connected to.
    
            
    
              
    
                from any computer on your network
                
    
              
    
              
    
            
    
            
    
              Or check from this page
              
    This works when ci-server is reached over https (Tailscale Serve or a Cloudflare Tunnel both work) or runs on this computer. Browsers block a plain http address on your network, so use the commands above for that.
    
              
    
                
    
                  
    
                    
                    
                    
    An https address, or localhost.
    
                  
    
                  
    
                    
                    
                    
    From your .env, or the Voice API key on the Hub app page. It goes only to the address above.
    
                  
    
                  
                  
    
                
    
                
    
                  
      
                    
    • waitingRun the check to see each part.
      • 
                  
    
                
    
              
    
            
    
            
    Then say the wake word and ask something only your Companion would know.
    
          
    10. 
        

      

    


    

      

        
Help

        
When something is off

        

          

            Home Assistant cannot connect
            
Wyoming is plain TCP, not a web address. Enter only the IP and port 10700, and check that no firewall blocks it. From the Home Assistant host, nc -vz <ip> 10700 should succeed.

          

          

            The Voice PE lights up but never answers
            
Run the check. A red language model row usually means the model is still downloading or was never pulled: docker compose -f compose.yml exec ollama ollama pull llama3.2.

          

          

            Speech-to-text returns nothing
            
With fully local voice, download the speech models once (the two curl lines in Start it). With the simplest setup, choose faster-whisper and Piper in the assistant instead of the companion ones.

          

          

            Answers do not use my memory
            
The key needs the memory scope, and the address must end in /api when you reach Companion Memory through its gateway. The check shows the exact error.

          

          

            The check here fails but curl works
            
Browsers block an https page from calling a plain http address on your network. Serve ci-server over https with Tailscale Serve or a Cloudflare Tunnel, or trust the curl result.