Everything technical about running InstantIoT Server, in one place. You don’t need any of this to get started — it’s here for when you want to look something up.
Where your data lives
The server keeps its database, backups, configuration, and JWT secret in one folder:
| Platform | Data folder |
|---|---|
| Raspberry Pi / Linux | /var/lib/instantiot/.instantiot/ |
| macOS | ~/.instantiot/ |
| Windows | %USERPROFILE%\.instantiot\ |
| Running from source | ~/.instantiot/ |
On Linux and Raspberry Pi, the server runs under a dedicated instantiot system user and installs to /opt/instantiot-server/.
Ports
| Port | Used for |
|---|---|
| 8080 | HTTP — admin panel and app connections |
| 9001 | TCP — ESP32 device connections |
Both need to be reachable from your local network.
Open them in the firewall if needed:
# Linux / Raspberry Pi (ufw)
sudo ufw allow 8080
sudo ufw allow 9001
On Windows, allow ports 8080 and 9001 under Windows Defender Firewall → Advanced settings → Inbound Rules → New Rule.
Managing the service (Linux & Raspberry Pi)
The server runs as a systemd service called instantiot-server:
systemctl status instantiot-server # is it running?
sudo systemctl restart instantiot-server # restart it
journalctl -u instantiot-server -f # watch the logs live
It starts at boot by default. Turn that off with sudo systemctl disable instantiot-server.
On macOS and Windows, the server runs as a normal app with a menu bar / system tray icon — quit it from there to stop it.
Reset the admin password
There’s no network-based recovery — by design, the admin panel has zero attack surface for password reset. Recovery is filesystem-based instead: anyone who can write a file on the server clearly owns the machine. Drop an empty file named reset-admin in the data folder and restart — the password goes back to admin and you’ll set a new one on next login.
# Linux / Raspberry Pi
sudo touch /var/lib/instantiot/.instantiot/reset-admin
sudo systemctl restart instantiot-server
# macOS / from source
touch ~/.instantiot/reset-admin
# then quit and relaunch the app
:: Windows
type nul > %USERPROFILE%\.instantiot\reset-admin
:: then quit from the tray and relaunch
Run from source
For contributors, or anyone who wants to audit or tweak the server. Requires JDK 21.
git clone https://github.com/jeanloickdt/instantiot-server.git
cd instantiot-server
./gradlew run # run locally
./gradlew buildFatJar # build a runnable JAR
java -jar build/libs/instantiot-server-all.jar
./gradlew packageInstaller # build a native installer for your OS
Contributions welcome — see CLA.md and CONTRIBUTING.md in the repo.
Troubleshooting
Port 8080 already in use. Set http.port=8081 in server.properties (in the data folder above), then restart.
.local address won’t resolve. Some networks block mDNS. Use the plain IP instead — find it with hostname -I (Linux/Pi), ifconfig (macOS), or ipconfig (Windows).
Phone can’t reach the server. Check both devices are on the same Wi-Fi, the firewall allows port 8080, and the server is actually up: curl http://localhost:8080/api/status.
Service won’t start (Linux/Pi). Look at the last 50 log lines: sudo journalctl -u instantiot-server -n 50. The Java runtime is bundled, so it’s almost always a port conflict.
Uninstall. sudo apt remove instantiot-server on Linux/Pi, drag to Trash on macOS, Add/Remove Programs on Windows. To erase your data too, delete the data folder listed above.
Open source under AGPLv3: github.com/jeanloickdt/instantiot-server.