Shed is a small, shared dashboard for households that keep animals together. One person feeds, another mists, someone logs a weight — Shed keeps a single calm care list that works across everyone's phones, credits each keeper by name, and turns completed care into history you can actually use: feeding records, weight trends in grams, and an append-only husbandry log.
The idea: today's care should be visible to the whole household, and yesterday's care should never be lost.
Quick start
New to Shed? The complete getting-started guide explains first login, the recommended enclosure → animal → care-plan setup order, household accounts, backups, and phone installation.
Shed runs as a Docker container on any always-on machine on your home network — an old PC, a NAS, a home server, or a Raspberry Pi.
curl -fsSL https://animalroom.app/shed/install.sh | bash
The installer downloads a prebuilt Shed image, turns on sign-in, and saves a one-time setup token in shed/.env. Nothing is compiled on your machine.
- Open
http://your-server:3000 on your phone or computer.
- Enter the setup token and create your Head Keeper account.
- Save the recovery access code it shows you (once).
- Add your animals, enclosures, and care plans — then invite the rest of the household.
Re-run the same command any time to update Shed. Before interrupting a running
install it verifies a SQLite backup, and if startup fails it restores the exact
previous Compose settings, image, and running state.
Requirements: Docker with the Compose plugin, and a machine that stays on.
Once Shed contains records, safe updates also require the small sqlite3 command
(sudo apt-get install -y sqlite3 on Raspberry Pi OS/Debian). If it is missing,
the installer leaves the current service running and tells you how to add it.
Shed is published as a multi-architecture image, so 64-bit Raspberry Pi OS,
Debian, Ubuntu, a NAS, and an x86 box all pull the right build automatically.
Shed needs about 400 MB of free memory to start — measured at 154 MB resident
moments after startup, with headroom for the pull and first-run migrations. On a
small board that means Raspberry Pi OS Lite rather than a desktop session.
Prefer to write the two files yourself? That works too — Shed is an ordinary
compose service:
mkdir -p ~/shed && cd ~/shed
curl -fsSLO https://raw.githubusercontent.com/jlyfshhh/shed/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/jlyfshhh/shed/main/.env.example -o .env
# replace both example secrets and set SHED_UID/SHED_GID to `id -u`/`id -g`
mkdir -p data backups && chmod 700 data backups && chmod 600 .env compose.yaml
docker compose up -d
The installer performs that ownership and permission setup automatically,
including repairing data files left by older root-running images. The container
runs without Linux capabilities, with a read-only application filesystem and
bounded memory, CPU, and process counts. Only the SQLite data mount and two
ephemeral scratch mounts are writable.
For one chooser that can install Bask, Shed, or both with their combined room
dashboard, use the Haven installer.
Shed + Bask = Haven
Shed can run by itself, or alongside Bask:
| Project | What it watches |
|---|
| ☀️ | Bask | The environment — live temperature & humidity from Bluetooth sensors, on a wall display |
| 🐍 | Shed (this repo) | The care — feeding, weights, enclosure work, schedules, and history for terrestrial animals |
| 🌿 | Haven | The combined room view — enclosure status and today's remaining care in one glance |
Haven is not a third database. It is the secure, read-only room dashboard that
appears when Bask and Shed are installed together. The apps remain separate, so
either can still work independently and each keeps its own portable data.
What's inside
- Shared daily care list across everyone's phones, with a one-day carryover so nothing slips.
- Household accounts — a Head Keeper who manages everything, and completion-only Keepers who view Shed and mark scheduled care done from their own phones. Every completed task is credited to the person who did it, with a per-member contribution report.
- Full record management — add and edit animals (with morph, sex, scientific name, enclosure, source, and notes), enclosures, care plans, husbandry notes, equipment, weights, and feeder inventory, all from the app.
- Private-by-default sharing — the Head Keeper can make a 1080×1350 PNG of today’s care for Instagram or messages. Animal names are opt-in; keeper identities, codes, rewards, notes, network addresses, IDs, and history are never included.
- Animal profiles — a per-animal card with a photo, weight history, care plans, equipment, notes, and full auditable event history.
- Photos — add a portrait from your phone; Shed resizes it in the browser, stores it in your own database, and includes it in your backup.
- Lighting plans — paste a Light My Reptile exact-setup link and Shed names every fixture for you, from a product list its developer supplied. It preserves a permanent reviewed snapshot, creates or matches installed equipment, returns to the live configuration, and tracks measured UVI/lux/temperature history.
- Editable care plans — daily, weekly, every-N-day, monthly, and one-time routines per animal.
- Feeder tracking & forecasting — feeder inventory counted by species and size class, with meal forecasting that matches each scheduled feeding to stock of the right species and size.
- Weight trends in grams.
- Correctable history — fix a mistaken entry without erasing the record; corrections stay auditable.
- Backups you control — JSON and CSV exports, in-app restore (merge or replace), dated SQLite snapshots, and portable lighting-plan attachments.
- Responsive phone and desktop layouts.
Data principles
- Records use ordinary relational tables and ISO timestamps.
- Append-only husbandry events preserve care history; corrections are retained, never silently deleted.
- JSON and CSV exports keep migration straightforward — your data is never trapped.
- Everything lives in a single self-hosted SQLite database with dated backups.
- Shed and Bask remain separate services so one app cannot take down the other.
Managing your install
- Update: re-run the install command. It validates the new configuration,
takes a verified backup, migrates older ownership safely, and restores the
prior image and settings if the new service does not become healthy. A raw
docker compose pull is not a safe substitute when crossing a runtime or
storage migration.
- Backups:
scripts/backup.sh writes dated SQLite snapshots (with configurable retention) into shed/backups. You can also download a full JSON or CSV export from the app at any time.
- Restore: the More screen accepts a Shed JSON export — merge it into your current data, or replace everything (your household sign-in stays intact).
- Add keepers: as the Head Keeper, open More → Household access to create a keeper and share their one-time code. You can reissue or disable codes any time.
Shed ignores client-supplied forwarding IP headers on a normal direct-LAN install.
If you put it behind a reverse proxy, leave SHED_TRUSTED_PROXY_IP_HEADER blank
unless the origin is reachable only through that proxy and the proxy strips and
overwrites the chosen header. The setting is solely an optional per-source login
throttle; authentication does not depend on an IP address.
Image releases include OCI source, revision, version, and license metadata plus
BuildKit provenance and an attached software bill of materials (SBOM). These
describe the published image; they do not replace verifying the release digest
when pinning a production install.
Local development
Shed is a Next.js 16 app that runs on Cloudflare Workers with a D1-compatible SQLite database (Drizzle ORM). Node 22.13+.
npm install
npm run dev
To run the container from your own checkout rather than the published image:
docker compose -f compose.yaml -f compose.dev.yaml up -d --build
The API contract the interface is built against lives in docs/backend-contract.md.
⚠️ Husbandry disclaimer
Shed records the care you decide on; it doesn't decide it for you. Feeding frequencies, schedules, and husbandry practices vary by species, age, and individual animal — verify your routine against trusted care resources. Shed is a tracking aid, not a substitute for proper research and care.
License
MIT — see LICENSE.
Built by jlyfshhh. I keep a room full of reptiles and amphibians — follow along on Instagram @thebioactivekeeper for the real animal room and bioactive builds behind these projects.
Shed is free, open-source, and local-first. If it helps your household, you can support Animal Room on Ko-fi. Tips help cover test sensors, Raspberry Pi hardware, the domain, and compatibility work.
Built with the help of AI assistants (OpenAI Codex and Anthropic's Claude). Reviewed, tested, and deployed by a human (me).
