Run the Spåna agent: Raspberry Pi, NAS or any Docker host

Spåna needs one always-on machine on the same network as your DIRIGERA hub. Almost anything qualifies: a Raspberry Pi, a NAS, a mini PC, a home server, or whatever box already runs the rest of your self-hosted stack. The agent is a small Go binary and will happily share a host with everything else on it.

This is the whole install. It takes about ten minutes, most of which is waiting for a Docker pull.

What you need

• An always-on machine on the same network as your hub. If it runs Docker, it works. A Raspberry Pi 3, 4 or 5 is the common case; a NAS, mini PC or old laptop is equally fine.
• An IKEA DIRIGERA hub with your sensors already added and named in the IKEA Home smart app. Spåna reads what is there; it does not replace that app.
• A Spåna account. The beta is free; sign up and copy your API key from the dashboard.

You do not need to forward any ports. The agent only makes outbound connections – to your hub on the LAN, and to the Spåna service. Nothing reaches in from outside.

Install with Docker

The image is public and multi-arch, so the same command works on a Pi 3 (ARMv7), a Pi 4 or 5 (ARM64), and an x86 box. No docker login needed:

docker run -d --name spaana-agent \
  --network host \
  -v spaana-agent-data:/data \
  -e SPAANA_API_KEY=<your key> \
  inellipse/spaana-agent:latest

Three things in that command are load-bearing:

--network host lets the agent see your LAN directly, which is what makes mDNS auto-discovery of the hub work. On Docker’s default bridge network multicast is dropped, discovery fails, and you have to type the hub’s IP by hand. It works but it is a worse first-run experience.

-v spaana-agent-data:/data persists the hub credentials the agent obtains when you pair. Skip it and you will re-pair the hub – including another walk to press the button on it – every time the container is recreated.

SPAANA_API_KEY is the only variable you have to set. The server address defaults to the hosted service, so hosted users supply nothing else. If you are self-hosting spaana-server, add -e SPAANA_SERVER_ADDR=<host:port>.

The container runs as a non-root user and publishes no ports.

Check it came up:

docker logs -f spaana-agent

You are looking for registered with server tenant_id=…. That means the bridge handshake succeeded and the agent is talking to the Spåna service. It will not say anything about the hub yet – that is the next step.

Pair the hub

The agent starts unpaired. Pairing happens from the web UI, not the command line, because it needs you to physically press a button.

Open the Spåna app, go to Pair your hub, and follow the wizard. It will either auto-discover the hub over mDNS (this is what --network host bought you) or ask for its IP address. Then it will tell you to press the action button on the underside of your DIRIGERA hub, and wait.

That button press is the hub’s consent mechanism – it is how DIRIGERA grants a new client access, and it is the same handshake the IKEA app performs. You have about ninety seconds, so start the wizard before you walk to the hub.

Once it completes, the logs show hub websocket connected and every sensor event starts flowing through. Your sensors, rooms and names come across as you set them up in the IKEA app.

Set your first alert

Group your sensors into rooms if you have not already, then add an alert. If you are not sure what to start with, pick something with a duration on it rather than something that fires on every event – a door left open for ten minutes teaches you more than a door opening.

We wrote up the reasoning behind that in why most smart-home alerts get ignored, and there are worked examples for four common situations if you want a starting point.

Install the iOS or Android app and the alert lands on your phone when it fires.

A note on macOS

Docker Desktop runs containers in a Linux VM that is not on your LAN. mDNS auto-discovery cannot work from in there, so the pairing wizard will ask you for the hub’s IP address rather than finding it by itself. Everything after that behaves the same – the agent still reaches the hub, and events still flow.

If you would rather not hand-enter an IP, a native install is the answer.

Homebrew

On a Mac, this is the better option for the reason above: a Homebrew install sits on your LAN properly, so hub auto-discovery works rather than making you type an IP. It works on Linux too, via Linuxbrew.

brew install inellipse/tap/spaana-agent

echo 'SPAANA_API_KEY=<your key>' >> "$(brew --prefix)/etc/spaana-agent.env"
brew services start spaana-agent

brew services starts it on login and restarts it on crash. Config lives in that env file – only SPAANA_API_KEY is required – and paired hub credentials persist in $(brew --prefix)/var/spaana-agent, so they survive upgrades. Logs go to $(brew --prefix)/var/log/spaana-agent.log, and brew services info spaana-agent tells you whether it is running.

One caveat: commissioning a sensor over Bluetooth needs a permission grant that a background service cannot prompt for, so pair sensors through the IKEA Home smart app – or run the agent from a Terminal when you want to commission one.

Keeping it running

The agent is designed to be left alone. It reconnects on its own when the hub reboots, the Wi-Fi drops, or the host restarts – so the main thing is making sure the process comes back up. With Docker, add --restart unless-stopped to the run command and the container will come back with the host.

Two habits worth having:

• Give the host a static lease in your router. Nothing breaks if its IP changes, since the agent dials out rather than being dialled, but it makes everything else easier to reason about.
• Do not run it on a laptop that sleeps. It sounds obvious, but a sleeping host is the most common cause of “why did I stop getting alerts”. The agent cannot forward events while the machine is suspended.

That is it

One container, one API key, one button press. Hub credentials stay on your network – the agent holds them, the server never sees them – and there is nothing inbound to secure.

If you get stuck, mail us at [email protected]. We read all of it during the beta, and install friction is exactly what we want to hear about.

Spåna is not affiliated with or endorsed by IKEA.