How it all works.

Getting started

The installer downloads the project to ~/personal-homelab-server, asks its few questions first, installs what is missing (Docker on a Mac comes through Colima), starts everything and opens the dashboard at http://localhost:3095.

The setup wizard in the dashboard takes it from there: your name and home city, a PIN for the settings, AI models suggested for your hardware, the optional apps, your calendar and the Telegram bot. Every step can be skipped and done later from Settings.

Two folders matter:

• ~/personal-homelab-server is the code. Updates replace it.
• ~/.homelab is your data: journal, notes, workouts, backups. Updates never touch it, and it is never part of the code.

Settings

Most settings live in the dashboard under Settings. Behind them are two files, both ignored by git:

• stack/config.yaml: your name, time zone, home city, briefing times, AI models and feature switches. Every line is optional; anything left out uses the default. Edit it safely with homelab config edit.
• stack/.env: the Telegram token, passwords for the optional apps and where things live. The installer fills it in.

Times are written the way you say them, such as "7:00 AM". To keep your settings in your own private git repository, use homelab settings-sync. It never copies your journal, passwords or PIN.

Access from other devices

The dashboard listens on this machine only. To open it from your phone or laptop at home, set a settings PIN first, then:

homelab access local goes back to this machine only. For access away from home, a private network such as Tailscale is the safe choice; set its address as dashboard_url so the bot's buttons open the right page.

Modules

Each feature is a module: a folder in modules/ with a module.yaml and a register(app) function. Modules never import each other, so any one can be switched off without breaking the rest.

briefing

A short morning briefing with news, weather, your calendar and a server recap.

day

Today and tomorrow, an evening plan with a suggested alarm, and a weekly report on Sundays.

journal

Write your day. Optional private nightly summary, weekly recap and insights, on your own machine.

gym

Workouts, sets and body weight, with history, records and progress charts.

health

Medicines on your own schedule and appointments you add yourself, with optional Telegram reminders. Reminders only, never medical advice.

planner

Notes, one-off or repeating reminders and long-term goals, in plain words.

news

Headlines by topic, short AI digests and news search.

weather

Now and tomorrow, for home or any city.

calendar

What is on today and tomorrow, from a secret iCal link.

flights

Finds flights in your calendar and says when to leave.

gmail

A short list of important email. Off until you add a Gmail app password.

search

Fresh answers with sources. Send a link, photo or voice note to get it summarised.

server

Is anything down, how hot is the CPU, restart an app, read its logs.

clock

The time in the cities you choose, compared with home.

currency

Convert amounts, and see your home currency abroad.

location

Where you are, so the weather follows you.

sports

F1 and cricket: the next race, standings and live matches.

alerts

Problems recorded quietly and read out in the morning recap.

ai

Which AI models are loaded, tokens used per feature, load or unload by hand.

Want your own? Copy modules/_template; the module guide walks through it in about 15 minutes.

Medicines

In the Health tab (it shows your first name), tap + Add. Give the medicine a name, how much if you like, and how often:

• Every day, at one or more times.
• Every week, on the day you pick.
• Every 2 weeks, from a first date. The form shows the next three dates so you can check it.
• Every month, on a date from 1 to 28.

Add Stop after for a course with a set number of doses. Today shows each dose by time, ready to tick. Coming up shows the next weekly or monthly ones and your appointments (+ Appointment). Tap any medicine or appointment to change or delete it.

Reminders: once the Telegram bot is connected, each medicine has a Remind me on Telegram switch. At each time the bot sends a message with Done, 5 min and 15 min. Without Telegram the switch is not shown, and nothing is sent. You can also just tell the bot "took my magnesium".

Pills left: type how many you have and how many per dose. Each tick takes them off, and the bot reminds you to refill 5 days before they run out. This month shows a calendar: green when everything was taken, amber when some was, red when a day was missed. Tap a day to see it. Quiet hours (under Reminders) make reminders in those hours arrive without a sound. Home shows the next medicine due, with a tick.

It is a tick-list to help you remember, not medical advice. Always follow your doctor.

Money

In your-name tab, switch to Money. The first time, it asks three things:

1. Your currency. One for everything; you can change it later.
2. Your income each month, as it lands in your account.
3. Your bills each month, and the day each is charged. For now only bills that come every month; yearly and quarterly bills are coming soon.

Then it shows what you can spend today: what is left after every bill this month, paid yet or not, shared over the days left, today included. Tap + Spent when you spend; it comes off today, and the days after share what remains, so an unexpected cost is never hidden.

Names and amounts stay hidden (R***, $****) until you tap Show, and hide again after a minute or when you leave the tab. With a settings PIN, Show asks for it. Nothing about money is ever sent to Telegram.

Optional apps

Nothing is installed that you did not choose. Pick them in the setup wizard or any time later:

ollama

Local AI engine (Ollama). AI models on this machine. On a Mac it can run outside Docker to use the Apple GPU.

open-webui

AI chat (Open WebUI). A ChatGPT-style page for your local models.

whisper

Voice to text (Whisper). Turns Telegram voice notes into text.

monitoring

Monitoring (Prometheus and Grafana). Server health, app status and charts.

uptime-kuma

Website monitor (Uptime Kuma). Checks that your websites are up.

dozzle

Live logs (Dozzle). Every app's log in the browser.

searxng

Private search (SearXNG). Web search for the assistant without tracking.

n8n

Automations (n8n). Connect apps and build workflows.

homepage

Full dashboard (Homepage). One page with links to every app.

adguard

Ad blocker (AdGuard Home). Blocks ads for your whole network. Needs port 53 and a machine that is always on.

Your own Docker apps get a tile on the dashboard too. Pin an exact version, never :latest:

Telegram bot

1. In Telegram, message @BotFather and send /newbot. Pick any name.
2. Paste the token it gives you into the setup wizard (or Settings).
3. Send your new bot /start. The wizard picks up your chat id, and from then on the bot answers only you.

Then talk to it in plain words: "remind me to water the plants tomorrow", "weather in Paris", "any important emails", "is anything down". Voice notes work once the Whisper app is added.

Backups

Open Settings, Backups (it needs the host helper, homelab agent install):

• Every night at a time you pick, keeping the last 3, 7, 14 or 30 in ~/.homelab/backups. Back up now makes one straight away.
• A copy on another drive: pick a plugged-in drive, or type a folder (a NAS, iCloud Drive, Dropbox). If the drive is not plugged in, the page says so and the copy goes within 5 minutes of plugging it back in.
• Lock the copies with a passphrase (8 or more characters). If you forget it, nobody can open those copies, not even you.
• Restore any backup in the list. A copy of how things are now is made first, so it can be undone.
• Alerts on Telegram, at most once a day each: a backup that failed, a copy that could not go, the disk nearly full, or the assistant stopping. They come from the host helper, so they arrive even when the assistant is down.

The same from the terminal:

A locked copy from your drive restores the same way (homelab restore /Volumes/Backup/Homelab/<file>.enc); it asks for the passphrase if this machine does not have it.

Updates

Shows what changed and asks first. Then it takes a snapshot, moves to the new version, updates saved data, restarts and checks health. If anything fails it goes back to the previous version by itself.

• Stable (the default) follows tagged releases.
• Edge follows every change on main: homelab update --channel edge.
• homelab update --check only tells you if something is new.
• The dashboard checks when you open it, and remembers the answer for 10 minutes. To check right away: Settings, Updates, Check now.
• With the Telegram bot connected, it also says so on Telegram once per version, with the notes and an Update now button. Turn it off in Settings, Updates.
• Most updates take seconds: only a change to the assistant's Python packages needs a rebuild.

When a new version is out, the dashboard shows a popup with what it brings, sorted into three kinds so you can tell at a glance:

• Security (amber): fixes that keep your data and server safe. Update soon.
• New (blue): new features.
• Fixed (green): bugs that are gone.

Tap Update now to run the same safe update from the dashboard (it needs the host helper, homelab agent install), or Later to hide it until the next version. After an update, Home shows what changed, and Settings, Updates lists the last five releases. Read the release notes before a major version of an optional app; some migrate their data and cannot go back, so take a backup first.

Community modules

Each feature is a module: one folder with a module.yaml and a little Python. You can build your own in 15 minutes and share it as a git repository.

To add one someone shared (read its code first: a module can see your data, like the built-in ones):

Then homelab restart. It shows in Settings, Modules, and updates leave it alone. Shared modules are listed in community-modules.md; add yours with a pull request.

Command reference

homelab help shows the same list in the terminal.

Troubleshooting

Start with homelab doctor. It checks Docker, every app, the AI engine, Telegram, the calendar and the internet, and prints a fix for each problem.

homelab: command not found

Run ~/personal-homelab-server/bin/homelab path add once, then open a new terminal.

The dashboard does not open

Run homelab status. If something is down, homelab logs telegram-bot shows why, and homelab restart usually brings it back.

Docker is not running

On a Mac, homelab autostart on starts it after every restart. homelab doctor says exactly what is missing.

The AI features say they are unavailable

Add the local AI engine with homelab apps add ollama, or pick models that fit your machine in the setup wizard. Everything else keeps working without it.

The bot does not answer

Check the token and chat id in the dashboard settings, then homelab restart. Only your own chat id gets answers.

homelab says it is up to date, but the dashboard shows an older version

Before 0.2.1 the command could run another copy of the project, such as a clone you work in. Run: cd ~ && ln -sfn ~/personal-homelab-server/bin/homelab ~/.local/bin/homelab, then homelab update. From 0.2.1 it always runs its own copy.

Backups: the drive is not plugged in

Plug it in. The host helper checks every 5 minutes and copies the newest backup as soon as it is back. The backup itself is safe on this machine.

Backups: macOS blocked access to the drive

Open System Settings, Privacy & Security, Files and Folders (or Full Disk Access) and allow python3. The copy runs by itself after that.

Money shows stars

That is on purpose. Tap Show; with a settings PIN it asks for it. Amounts hide again after a minute.

An update failed

It has already gone back to the previous version. Run homelab doctor, then open an issue with what it printed.

Still stuck? Open an issue with what homelab doctor printed, after removing anything personal, or ask in Discord #homelab.

Privacy and safety

• Everything runs on your machine. The only outside calls are for features you use, such as weather and news feeds.
• AI runs locally with Ollama. A cloud model is used only if you add your own key.
• The dashboard is local-only until you open it to your network with a PIN.
• Every Docker image is pinned to an exact version.

This is a personal-organisation tool, not a medical device, and it gives no medical, psychological, legal or financial advice. Read the disclaimer. Security problems: report them privately through the security policy.