FAQ & Troubleshooting¶

Before Installing¶

What is Eight.ly?¶

For the home or small-business server, Eight.ly OS replaces your NAS, your container manager, and your VM and LXC host with one system. It's a curated catalog of 3,200+ self-hosted apps — media servers, download clients, AI tools, home automation, and more — a full storage stack, virtual machines, and Nova, a local AI assistant, all in one dashboard. Click Deploy and you're running.

What do I need to run it?¶

Eight.ly OS installs from a bootable image — on bare metal or in a VM. It also runs on arm64 hardware. Linux only; there's no Windows or macOS host version (a Mac can run it in a VM).

I'm new to Docker. Can I still use this?¶

Yes — that's the point. Eight.ly was built so you don't have to write Docker Compose files just to run Plex or Nextcloud. Docker is built into the OS image and managed for you; you never install or configure it yourself. The Quick Start guide walks through every step.

How is this different from Portainer?¶

Portainer is a general container management tool — powerful, but you need to know what you want to run. Eight.ly gives you a curated catalog of 3,200+ homelab apps with one-click deployment, plus storage, VMs, and an AI assistant Portainer doesn't have. Think of it as an app store and NAS built around your server, not just a Docker UI.

How much does Eight.ly cost?¶

Eight.ly ships as one product, sold as two license types:

Buy once — the version you install keeps running for as long as you want it. A year of updates is included; extending afterward is optional, not a subscription. The Eight.ly Backup Server and the remote Agent are included free with every license. See Pricing and eight.ly for current figures.

Where do the app catalog apps come from?¶

The catalog of 3,200+ apps is curated and maintained by Eight.ly in the private imogenlabs/eightly-templates repo. No external feed, no upstream dependency — the catalog is self-contained. Container images are pulled from wherever the publisher ships them (Docker Hub, GHCR, Quay, LinuxServer.io, etc.).

After Installing¶

The dashboard loads but no apps show up ("Failed to load applications")¶

The catalog is fetched from the license-gated catalog API, not a local clone — check Settings > License and confirm your license activated. If the license server is unreachable, Eight.ly keeps running and serves whatever was already cached; new apps just won't show up until connectivity returns. See Licensing.

"Port already in use"¶

Something else on the box is already using port 8080. Find it:

sudo ss -tlnp | grep 8080

Free that port, or stop whatever's holding it.

Docker socket permission denied¶

Eight.ly needs /var/run/docker.sock to manage containers. Confirm Docker is running:

sudo systemctl status docker

If Docker's socket permissions changed after Eight.ly was already running, restart the service so it picks the change up:

sudo systemctl restart eightly

Running Eight.ly OS in a Proxmox VM¶

Boot the ISO in a Proxmox VM the same way you would on bare metal — it needs its own kernel, so it runs as a full VM, not as an LXC container.

Deploying Apps¶

What are the three deployment modes?¶

1. Standard — simplest. App gets a port, access it at http://your-server:PORT. No extra setup. Choose this if you're not sure.
2. Traefik — real URL like https://plex.yourdomain.com with automatic free SSL. Requires a domain and Traefik. (Setup guide)
3. Traefik + Authelia — same as Traefik, plus a login page in front of the app. Recommended for anything internet-facing.

My deployed app isn't accessible¶

Work through these in order:

docker ps | grep app-name         # Is it running?
docker logs app-name --tail 30    # Any errors?
docker port app-name              # What port did it get?
sudo ufw allow PORT/tcp           # Firewall blocking it?

Security¶

What's the default login?¶

There is no admin/admin default. The first time you open the dashboard, you create the admin account yourself — you pick the username and password (POST /api/auth/setup), so there's no shared default credential to change. Whatever password you set is the only way in; keep it strong and don't reuse it. (Some pre-seeded demo/dev boxes ship with admin/admin123 — if you're on one of those, change the password immediately after signing in via your username menu in the top right.)

Should I expose Eight.ly to the internet?¶

Only with authentication in front of it. Use Traefik + Authelia mode for any app you expose publicly. Never put an unauthenticated dashboard on the public internet.

What are API keys and when should I use them?¶

API keys (eos_ prefix) are long-lived credentials for scripts, automation, and the mobile app. They don't expire until you revoke them. Your browser session is fine for interactive use, but not for automation that runs overnight.

Key rules: - Keep API keys out of public repositories - Revoke keys for devices you no longer use (Settings > Security > API Keys > Delete) - The full key is shown only once when created — save it somewhere safe

How do I keep the Docker socket secure?¶

Mounting /var/run/docker.sock gives Eight.ly control over Docker on your server. For most homelabs this is fine. If you want to restrict what it can do, use Docker Socket Proxy — it sits between Eight.ly and Docker and lets you allow only specific API calls.

Data & Backups¶

Where's my data?¶

• App configs and data: /opt/appdata/ — each deployed app gets its own subfolder
• Eight.ly settings (users, sessions, license): /etc/eightly/ and the SQLite database at /var/lib/eightly/eightly.db

How do I back up everything?¶

sudo tar -czf eightly-backup-$(date +%Y%m%d).tar.gz /opt/appdata/

For automated, deduplicated, encrypted backups, use the Eight.ly Backup Server (EBS) — it's included free with your license.

How do I update to the latest version?¶

Click Check for Updates in the dashboard header. Featherfall downloads the release, verifies it, swaps the binary and dashboard assets, and rolls back automatically if the post-update health check fails — no reinstall needed. Changes to the kernel, systemd unit, or Debian packaging still need the ISO installer path; Featherfall tells you when a release requires that instead.

Advanced Topics¶

Can I add my own apps?¶

Yes. From the dashboard's app install flow, you can deploy any Docker Compose file, not just catalog entries — paste in your own Compose YAML with ${VARIABLE} placeholders (${TZ}, ${APPFOLDER}, ${ID}, ${DOMAIN}) and it deploys the same way a catalog app does. See How the App Catalog Works for the full template format, and Web Dashboard for the day-to-day flow.

How does authentication work?¶

Two options: signed-cookie browser sessions (from POST /api/auth/login) and API keys (eos_ prefix, permanent until revoked). The dashboard uses the signed-cookie session. For scripts, automation, and the mobile app, use API keys.

Can I disable the login screen?¶

No — authentication is always on, by design. There's no setting or environment variable that turns off the login screen; Eight.ly manages Docker, VMs, and storage directly, so an unauthenticated API would hand out root-equivalent control to anyone who can reach the box.

How do I set up multiple users with different roles?¶

Go to Settings > Dashboard Users and add a user, then assign a role from Settings > Roles & Permissions. Built-in roles:

• Admin — full access to everything, including user management and security settings
• Operator — can deploy apps, manage containers, and view storage, but can't manage users or security
• Viewer — read-only access to the dashboard, monitoring, and logs

Create Operator accounts for family members who help manage the server. Use Viewer for monitoring-only access (e.g., a wall-mounted dashboard).

What hardware do I need for different workloads?¶

Can I limit CPU or RAM per container?¶

Yes. When deploying an app, you can set resource limits in the deploy modal's advanced settings. You can also edit limits after deployment from the container's detail panel.

How do I connect the mobile app?¶

Eight.ly Mobile has not been released yet. When it ships, you'll create an API key in Settings > Security > API Keys, install the app, and connect it to your server URL with that key. See the Mobile App guide for the current status.

What can Nova AI do, and what's blocked?¶

Nova has 41 tools for reading and controlling the system — 27 read-only, 14 mutating. It can answer questions like "what containers are running?" or "show SMART status for /dev/sda," and it audit-logs anything that changes state. Mutating operations Nova considers risky are blocked in the UI, which points you to where to do it yourself instead of guessing at an ambiguous request. See the Nova AI guide.

What happens if my license lapses?¶

The version you have keeps running indefinitely — every feature, no lockout. You stop getting App Store catalog updates and product updates; security fixes still install. If you're on a trial rather than a paid license, a lapsed trial additionally stops you creating new apps, VMs, containers, shares, and backup jobs until you activate — everything already running is untouched. See Licensing.

How does Eight.ly pricing compare to alternatives?¶

See the full comparison for feature differences.

Getting Help¶

• Discord — fastest, someone's usually around — ask in #help; also the place for bug reports and feature requests
• eight.ly — product page + current pricing