Skip to content

Home

Jump to bottom
Fins1600 edited this page May 11, 2026 · 5 revisions

Weekaroo Wiki

Weekaroo is a local-first wall dashboard for families, roommates, classrooms, and small teams. It runs on hardware you control and shows a weekly calendar, local weather, rotating notes, timers, countdowns, daily facts, and optional AI-generated dashboard messages.

Repository: https://github.com/Fins1600/weekaroo

What Weekaroo is for

Weekaroo is designed for:

  • Kitchen, hallway, classroom, or roommate dashboard screens
  • Spare laptops, mini PCs, Raspberry Pi devices, wall tablets, or local network displays
  • Families or groups that want calendar + weather + notes + timers + countdowns in one glanceable place
  • People who want local config files instead of another hosted dashboard subscription

Weekaroo may be more than you need if all you want is a shared Google Calendar. It starts making sense when the screen is meant to be an always-on household board.

Core features

  • 7-day calendar view from one or more ICS calendar feeds
  • Local weather by ZIP/postal code
  • Optional WeatherFlow Tempest support
  • Rotating family messages and event-matched message rules
  • Countdowns and count-up timers with themed popups
  • Day notes for quick reminders
  • Optional OpenAI-compatible AI message generation, handled server-side
  • Local-first configuration, no hosted account required

Start here

Project posture

Weekaroo is MIT licensed and meant to be easy to run, inspect, and customize. It is intentionally local/LAN-oriented. Do not expose it directly to the public internet without adding authentication, HTTPS, and a real threat model.

Wiki page: Quick-Start

Quick Start

Install and run

git clone https://github.com/Fins1600/weekaroo.git
cd weekaroo
chmod +x install.sh run-dashboard.sh run-demo.sh
./install.sh
./run-dashboard.sh

Then open:

http://127.0.0.1:4020

Headless or kiosk install

If you do not want a desktop shortcut, run:

INSTALL_DESKTOP_SHORTCUT=0 ./install.sh

If you do not want the launcher to open a browser automatically, run:

OPEN_BROWSER=0 ./run-dashboard.sh

Run on a different port

The default port is 4020. If another dashboard is already using that port, choose another one:

PORT=4021 OPEN_BROWSER=0 ./run-dashboard.sh

Then open:

http://127.0.0.1:4021

Demo mode

To evaluate Weekaroo without personal data:

OPEN_BROWSER=0 ./run-demo.sh

Demo mode copies synthetic demo files into the local ignored config names, then starts the dashboard.

Wiki page: Configuration

Configuration

Weekaroo stores local settings in JSON files. Private config files are ignored by git so you can keep calendar URLs, notes, tokens, and local preferences out of the public repository.

Calendars

Weekaroo includes a US Holidays calendar by default. Add personal or shared calendars from Settings → Calendars, or edit calendars.json manually.

Example:

[
  {
    "id": "us-holidays",
    "name": "US Holidays",
    "url": "https://www.officeholidays.com/ics/usa",
    "color": "#f59e0b",
    "enabled": true
  },
  {
    "id": "family",
    "name": "Family",
    "url": "https://calendar.example.com/family.ics",
    "color": "#7dd3c7",
    "enabled": true
  }
]

Messages, countdowns, timers, and day notes

Create local config files from examples:

cp family-messages.example.json family-messages.json
cp countdowns.example.json countdowns.json
cp day-notes.example.json day-notes.json

Timers and day notes can also be edited from the dashboard settings UI.

Weather

By default, Weekaroo uses public weather by ZIP/postal code. Weather settings can be edited in Settings → Weather.

WeatherFlow Tempest is optional. If you use it, enter the station ID and token in Settings → Weather. The token is stored server-side in weather-config.json, which is ignored by git.

Optional AI messages

Settings → AI supports OpenRouter or another OpenAI-compatible endpoint.

Recommended secret handling:

export OPENROUTER_API_KEY="your-key"
# or
export DASHBOARD_AI_API_KEY="your-key"

You may also save a key in ai-config.json, but never commit that file.

Wiki page: Raspberry-Pi-and-Linux-Kiosk-Setup

Raspberry Pi and Linux Kiosk Setup

Weekaroo works well as a local wall display on a Raspberry Pi, mini PC, spare laptop, or Linux kiosk machine.

Basic run

git clone https://github.com/Fins1600/weekaroo.git
cd weekaroo
chmod +x install.sh run-dashboard.sh run-demo.sh
INSTALL_DESKTOP_SHORTCUT=0 ./install.sh
OPEN_BROWSER=0 ./run-dashboard.sh

Open Chromium to:

http://127.0.0.1:4020

Chromium kiosk command

chromium-browser --kiosk --app=http://127.0.0.1:4020

On some distributions the executable is named chromium instead:

chromium --kiosk --app=http://127.0.0.1:4020

LAN viewing

From another device on the same network:

http://<dashboard-computer-ip>:4020

Do not expose port 4020 directly to the internet. If you need remote access, put authentication and HTTPS in front of it.

Demo mode on a kiosk machine

OPEN_BROWSER=0 ./run-demo.sh

Then open the same local or LAN URL above.

Wiki page: Screenshots-and-Demo-Data

Screenshots and Demo Data

Public screenshots should use only synthetic data.

Recommended screenshot process

Copy the demo files into local config names:

cp demo/calendars.demo.json calendars.json
cp demo/family-messages.demo.json family-messages.json
cp demo/countdowns.demo.json countdowns.json
cp demo/timers.demo.json timers.json
cp demo/weather-config.demo.json weather-config.json

Start Weekaroo:

PORT=4020 ./run-dashboard.sh

Capture screenshots that contain only demo calendar/message data.

Save public screenshots in:

docs/images/

Important rule

Never publish screenshots from a real family calendar, real weather station, private notes, private messages, or real API-backed setup.

Wiki page: Privacy-and-Secrets

Privacy and Secrets

Weekaroo is local-first, but it can display sensitive information from calendars, notes, weather stations, and AI providers. Treat configuration files as private data.

Never commit or publish

  • Calendar feed URLs
  • WeatherFlow Tempest station tokens
  • OpenRouter/OpenAI-compatible API keys
  • Personal notes or private family messages
  • Generated weather history from a private location
  • Screenshots containing real calendar events, notes, private locations, or family data

Git-ignored private files

Do not publish these files:

  • calendars.json
  • family-messages.json
  • countdowns.json
  • timers.json
  • weather-config.json
  • ai-config.json
  • weather-history.json
  • day-notes.json

Pre-publish check

Before publishing screenshots, configs, or generated artifacts, run:

grep -RInE "apiKey|token|secret|BEGIN|sk-|Bearer|calendar.*ics|@|address|street" . --exclude-dir=.git

Review every hit manually.

Network exposure

Weekaroo is designed for local/LAN use. Do not expose it directly to the internet without adding authentication, TLS, and a deployment-specific threat model.

API keys are never returned to the browser by the built-in settings endpoints.

Wiki page: FAQ

FAQ

How is Weekaroo different from MagicMirror?

MagicMirror is mature and modular. Weekaroo is intentionally simpler and focused on a family-style wall board: calendar, weather, notes, timers, countdowns, and optional AI messages without module wrangling.

How is Weekaroo different from DAKboard or other hosted dashboards?

Hosted dashboards are easier if you want cloud sync and managed accounts. Weekaroo keeps configuration local and does not require a dashboard subscription.

Can I run Weekaroo on the same machine as another dashboard?

Yes. Run each dashboard on a different port. Weekaroo defaults to 4020, but you can change it:

PORT=4021 OPEN_BROWSER=0 ./run-dashboard.sh

Can I view Weekaroo from another device?

Yes, from another device on the same LAN:

http://<dashboard-computer-ip>:4020

Do not expose the port directly to the public internet.

Does Weekaroo need an account?

No. Weekaroo is local-first and uses local config files.

Does AI message generation send my calendar data to an AI provider?

Only if you enable AI messages. If enabled, the dashboard sends the schedule/weather context needed for message generation to your configured OpenAI-compatible endpoint. Keep this disabled if that does not fit your privacy needs.

What license does Weekaroo use?

Weekaroo is released under the MIT License.

Clone this wiki locally