{"id":51410814,"url":"https://github.com/momenbasel/timenest","last_synced_at":"2026-07-04T14:32:30.925Z","repository":{"id":352978131,"uuid":"1217462675","full_name":"momenbasel/timenest","owner":"momenbasel","description":"Network Time Machine for every Mac on your LAN. Runs on Mac mini, Raspberry Pi, or any home server. Docker stack: Samba + vfs_fruit, Avahi Bonjour discovery, FastAPI admin UI.","archived":false,"fork":false,"pushed_at":"2026-05-14T22:35:05.000Z","size":2781,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T00:26:09.461Z","etag":null,"topics":["avahi","backup","bonjour","docker","fastapi","homelab","mac-mini","macos","network-backup","raspberry-pi","samba","self-hosted","time-capsule","time-machine","vfs-fruit"],"latest_commit_sha":null,"homepage":"https://github.com/momenbasel/timenest","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/momenbasel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["momenbasel"],"ko_fi":"momenbasel","custom":["https://greycorelabs.com"]}},"created_at":"2026-04-21T23:05:24.000Z","updated_at":"2026-05-14T22:35:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/momenbasel/timenest","commit_stats":null,"previous_names":["momenbasel/timenest"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/momenbasel/timenest","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/momenbasel%2Ftimenest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/momenbasel%2Ftimenest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/momenbasel%2Ftimenest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/momenbasel%2Ftimenest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/momenbasel","download_url":"https://codeload.github.com/momenbasel/timenest/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/momenbasel%2Ftimenest/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35125718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avahi","backup","bonjour","docker","fastapi","homelab","mac-mini","macos","network-backup","raspberry-pi","samba","self-hosted","time-capsule","time-machine","vfs-fruit"],"created_at":"2026-07-04T14:32:29.167Z","updated_at":"2026-07-04T14:32:30.918Z","avatar_url":"https://github.com/momenbasel.png","language":"Shell","funding_links":["https://github.com/sponsors/momenbasel","https://ko-fi.com/momenbasel","https://greycorelabs.com"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/momenbasel/timenest/main/docs/social-preview.png?v=2\" alt=\"TimeNest - network Time Machine server for Mac mini, Raspberry Pi, and any Linux home server\" width=\"900\"\u003e\n\n### Network Time Machine for every Mac on your LAN.\n\nTurn an external drive on a **Raspberry Pi**, **Intel NUC**, or **any Linux home server**\ninto a Time Machine target. Zero cables. Zero Apple Time Capsule. Zero iCloud upsell.\n\n\u003csub\u003eAlready own a Mac mini? Use Apple's built-in [File Sharing -\u003e Time Machine destination](#running-on-a-mac-mini-read-this-first) instead - TimeNest is for hosts that don't already ship a Time Machine server.\u003c/sub\u003e\n\n\u003e **TimeNest** is a free, open-source, self-hosted **Apple Time Capsule alternative**. It\n\u003e packages Samba 4.18 with `vfs_fruit`, Avahi for Bonjour discovery, and a FastAPI admin\n\u003e UI into one `docker compose` stack, so any Mac on your LAN finds it in Finder and in\n\u003e System Settings -\u003e Time Machine automatically, without typing an IP or mounting an SMB\n\u003e URL. Runs on macOS, Raspberry Pi OS, Debian, Ubuntu, Fedora, and Arch.\n\n\u003cbr\u003e\n\n[![build](https://img.shields.io/github/actions/workflow/status/momenbasel/timenest/docker.yml?branch=main\u0026label=build\u0026style=flat-square)](https://github.com/momenbasel/timenest/actions)\n[![release](https://img.shields.io/github/v/release/momenbasel/timenest?include_prereleases\u0026style=flat-square)](https://github.com/momenbasel/timenest/releases)\n[![license](https://img.shields.io/github/license/momenbasel/timenest?style=flat-square)](LICENSE)\n[![platforms](https://img.shields.io/badge/platforms-amd64%20%7C%20arm64%20%7C%20armv7-blue?style=flat-square)](#supported-hardware)\n[![samba](https://img.shields.io/badge/samba-4.18%2B-green?style=flat-square)](https://www.samba.org/)\n[![python](https://img.shields.io/badge/python-3.11%2B-3776ab?style=flat-square)](https://www.python.org/)\n\n\u003cbr\u003e\n\n**[ Quick Start ](#quick-start)** -\n**[ Install ](#installation)** -\n**[ Connect a Mac ](#connecting-a-mac)** -\n**[ Architecture ](#architecture)** -\n**[ FAQ ](#faq)** -\n**[ Troubleshooting ](#troubleshooting)**\n\n\u003c/div\u003e\n\n---\n\n## Why TimeNest\n\nApple discontinued the Time Capsule in 2018. Keeping a USB drive plugged into every Mac is fragile, and iCloud does not back up your full disk. TimeNest fills that gap with three design goals:\n\n1. **Plug-and-forget.** One Docker stack. One web UI. Runs on the hardware you already have.\n2. **True auto-discovery.** Your Mac finds the share in Finder and in System Settings without typing an IP or mounting an SMB URL.\n3. **Per-user quotas.** Household or team drives with hard size limits so one Mac cannot fill the disk.\n\n## Feature matrix\n\n| Capability                         | TimeNest | macOS File Sharing | Apple Time Capsule | Raw SMB share |\n| :--------------------------------- | :------: | :----------------: | :----------------: | :-----------: |\n| Runs on Mac mini                   |   Yes    |        Yes         |         -          |      Yes      |\n| Runs on Raspberry Pi 4 / 5         |   Yes    |         No         |         No         |      Yes      |\n| Runs on x86 / ARM Linux server     |   Yes    |         No         |         No         |      Yes      |\n| Runs inside a single Docker stack  |   Yes    |         No         |         No         |      No       |\n| Bonjour (mDNS) auto-discovery      |   Yes    |        Yes         |        Yes         |    Manual     |\n| Advertises as Time Capsule         |   Yes    |         No         |        Yes         |      No       |\n| Per-user size quotas               |   Yes    |         No         |         No         |      No       |\n| Concurrent multi-Mac backup        |   Yes    |        Yes         |        Yes         |    Partial    |\n| Disk health and SMART monitoring   |   Yes    |         No         |         No         |      No       |\n| Web dashboard with live status     |   Yes    |      Partial       |      Limited       |      No       |\n| Prometheus metrics endpoint        |   Yes    |         No         |         No         |      No       |\n| Alerts on backup failure           |   Yes    |         No         |         No         |      No       |\n| Still sold / supported by Apple    |   N/A    |        Yes         |       **No**       |      N/A      |\n\n## Architecture\n\n```mermaid\nflowchart LR\n    subgraph LAN[\"Home LAN\"]\n        M1[\"MacBook Pro\"]\n        M2[\"iMac\"]\n        M3[\"Mac Studio\"]\n    end\n\n    subgraph Host[\"Home server\u003cbr/\u003e(Mac mini / RPi / Linux box)\"]\n        direction TB\n        Web[\"Web UI\u003cbr/\u003e:8080\u003cbr/\u003eFastAPI + Jinja + htmx\"]\n        Samba[\"Samba + vfs_fruit\u003cbr/\u003e:445\u003cbr/\u003eTime Machine SMB share\"]\n        Avahi[\"Avahi mDNS\u003cbr/\u003e:5353\u003cbr/\u003e_adisk._tcp\u003cbr/\u003e_smb._tcp\u003cbr/\u003e_device-info._tcp\"]\n        Disk[(\"External drive\u003cbr/\u003eext4 / xfs / apfs\")]\n    end\n\n    M1 -- \"mDNS lookup\" --\u003e Avahi\n    M2 -- \"mDNS lookup\" --\u003e Avahi\n    M3 -- \"mDNS lookup\" --\u003e Avahi\n    M1 -- \"SMB3 backup stream\" --\u003e Samba\n    M2 -- \"SMB3 backup stream\" --\u003e Samba\n    M3 -- \"SMB3 backup stream\" --\u003e Samba\n    Samba --\u003e Disk\n    Web -. \"manages users,\u003cbr/\u003equotas, health\" .-\u003e Samba\n    Web -. \"reads SMART,\u003cbr/\u003edisk usage\" .-\u003e Disk\n\n    Admin[\"Admin browser\"] -- \"https :8080\" --\u003e Web\n```\n\n## Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/screenshots/02-dashboard.png\" alt=\"TimeNest dashboard - per-user disk usage, active SMB sessions, live backup status\" width=\"820\"\u003e\n\n\u003csub\u003e\u003cb\u003eDashboard\u003c/b\u003e - per-user usage, active SMB sessions, and drive health at a glance.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/03-users.png\" alt=\"TimeNest users page - per-user Time Machine quotas, used space, last backup\" width=\"100%\"\u003e\u003cbr\u003e\n\u003csub\u003e\u003cb\u003eUsers\u003c/b\u003e - create a Time Machine account per Mac, set a quota, remove in one click.\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/04-storage.png\" alt=\"TimeNest storage page - backup volume usage bar and SMART health panel\" width=\"100%\"\u003e\u003cbr\u003e\n\u003csub\u003e\u003cb\u003eStorage\u003c/b\u003e - backup volume usage and per-drive SMART health.\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/05-settings.png\" alt=\"TimeNest settings page - environment configuration, password rotation, Prometheus scrape target\" width=\"100%\"\u003e\u003cbr\u003e\n\u003csub\u003e\u003cb\u003eSettings\u003c/b\u003e - environment reference, password rotation, Prometheus scrape target.\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\n\u003cimg src=\"docs/screenshots/01-login.png\" alt=\"TimeNest login screen - dark gradient sign-in with TimeNest clock logo\" width=\"100%\"\u003e\u003cbr\u003e\n\u003csub\u003e\u003cb\u003eSign-in\u003c/b\u003e - single admin login; credentials configured via \u003ccode\u003e.env\u003c/code\u003e.\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Supported hardware\n\n| Host                             | Arch           |   Tested   | Notes                                                 |\n| :------------------------------- | :------------- | :--------: | :---------------------------------------------------- |\n| Raspberry Pi 5 (8GB) + USB 3 SSD | `linux/arm64`  |    Yes     | Best price / performance ratio, recommended target    |\n| Raspberry Pi 4 (4GB / 8GB)       | `linux/arm64`  |    Yes     | USB 3 recommended                                     |\n| Raspberry Pi 3B+                 | `linux/arm/v7` |     -      | Works but gigabit bottlenecks backup speed            |\n| Intel NUC / generic x86 server   | `linux/amd64`  |    Yes     |                                                       |\n| ARM VPS (Hetzner, Oracle, AWS)   | `linux/arm64`  |    Yes     | WAN backups need a VPN                                |\n| Mac mini M1 / M2 / M4 (macOS)    | `linux/arm64`  | Not recommended | **Use native macOS File Sharing instead.** See below. |\n| Mac mini 2018 (Intel)            | `linux/amd64`  | Not recommended | **Use native macOS File Sharing instead.** See below. |\n\nMinimum: 2 cores, 1 GB RAM, 100 Mbit LAN. Recommended: 4 cores, 2 GB RAM, gigabit LAN, USB 3 / SATA SSD target.\n\n\u003e ### Running on a Mac mini? Read this first.\n\u003e\n\u003e macOS already ships a Samba server bound to `:445` and an `mDNSResponder`\n\u003e owning `:5353`. Both are required by AirDrop, Finder network browsing,\n\u003e Handoff, Continuity, and AirPlay discovery. **TimeNest's containers\n\u003e cannot bind those ports without killing those services**, and you do\n\u003e not want to kill those services.\n\u003e\n\u003e If your host is a Mac mini, use Apple's built-in path instead:\n\u003e\n\u003e 1. `System Settings` -\u003e `General` -\u003e `Sharing` -\u003e turn on **File Sharing**.\n\u003e 2. Click the `i` -\u003e `+` under Shared Folders -\u003e select the external drive.\n\u003e 3. Right-click the folder -\u003e `Advanced Options` -\u003e tick **Share as a Time Machine backup destination** -\u003e set a quota if you want.\n\u003e 4. On the other Mac: `System Settings` -\u003e `Time Machine` -\u003e `Add Backup Disk` -\u003e pick the share.\n\u003e\n\u003e Bonjour advertisement is automatic. No Docker, no port conflicts, two minutes of clicking. TimeNest is designed for the case where you **do not** already have a running Time Machine server - Raspberry Pis, Linux boxes, NUCs. Consider it on a Mac mini only if you specifically need the web UI, per-user quotas, or Prometheus metrics, and you are willing to stop the native `smbd` (which disables several OS features).\n\n## Quick start\n\n```bash\n# 1. Clone\ngit clone https://github.com/momenbasel/timenest.git \u0026\u0026 cd timenest\n\n# 2. Tell TimeNest where your external drive is mounted\ncp .env.example .env\n$EDITOR .env   # set BACKUP_PATH=/mnt/your-drive and ADMIN_PASSWORD=...\n\n# 3. Bring the stack up\ndocker compose up -d\n```\n\nThen open `http://\u003cserver-ip\u003e:8080`, log in with the admin password you set, create a user for each Mac, and open System Settings on your Mac -\u003e General -\u003e Time Machine -\u003e Add Backup Disk. The share appears as **TimeNest** with a Time Capsule icon.\n\n## Installation\n\n### Homebrew (macOS)\n\n```bash\nbrew tap momenbasel/timenest\nbrew install timenest\ntimenest up\n```\n\n`timenest up` wraps `docker compose up -d` against the bundled stack. See `timenest help` for the rest. Docker Desktop or OrbStack is required and the formula prints a caveat if it is missing.\n\n### One-liner (Linux, Raspberry Pi, WSL)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/momenbasel/timenest/main/install.sh | bash\n```\n\nThe installer detects your OS and architecture, installs Docker if missing, prompts for the drive you want to use, writes `.env`, and starts the stack.\n\n### Manual, macOS (Mac mini) - **not recommended**\n\nUse [native macOS File Sharing](#running-on-a-mac-mini-read-this-first) instead. It already covers every TimeNest feature except the admin web UI, per-user quotas, Prometheus metrics, and SMART dashboard.\n\nIf you still want TimeNest on a Mac mini (for those features), be aware that `:445` and `:5353` are occupied by `smbd` and `mDNSResponder`. You must disable them before running the stack, at the cost of breaking AirDrop / Finder network browse / Handoff / AirPlay discovery:\n\n```bash\n# DESTRUCTIVE on the Mac mini - breaks OS features. Read the caveat above.\nsudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.smbd.plist\nsudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.mDNSResponder.plist\n\nbrew install --cask docker\nopen -a Docker                              # start Docker Desktop\n# Docker Desktop -\u003e Settings -\u003e Resources -\u003e Network -\u003e Enable host networking\ngit clone https://github.com/momenbasel/timenest.git\ncd timenest\ncp .env.example .env\n# edit .env: set BACKUP_PATH to a path shared with Docker Desktop\n#            (e.g. /Volumes/Backups). Enable it under\n#            Docker Desktop -\u003e Settings -\u003e Resources -\u003e File sharing.\ndocker compose up -d\n```\n\nTo reverse, re-load the LaunchDaemons with `sudo launchctl load -w ...` or reboot.\n\n### Manual, Debian / Ubuntu / Raspberry Pi OS\n\n```bash\nsudo apt update\nsudo apt install -y docker.io docker-compose-plugin git\nsudo usermod -aG docker \"$USER\" \u0026\u0026 newgrp docker\n\ngit clone https://github.com/momenbasel/timenest.git\ncd timenest\ncp .env.example .env\nnano .env\ndocker compose up -d\n```\n\n### Preparing the external drive\n\nTimeNest works with any filesystem Samba can serve, but a native Linux filesystem is strongly recommended for reliability and quota support.\n\n```bash\n# identify the drive\nlsblk -o NAME,SIZE,FSTYPE,MOUNTPOINT\n\n# format (DESTROYS DATA on the target device)\nsudo mkfs.ext4 -L timenest /dev/sda1\n\n# create a stable mountpoint and mount at boot\nsudo mkdir -p /mnt/timenest\necho 'LABEL=timenest /mnt/timenest ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab\nsudo mount -a\n```\n\nThen point `BACKUP_PATH` in `.env` at `/mnt/timenest`.\n\n## Connecting a Mac\n\n1. On the Mac, open **System Settings -\u003e General -\u003e Sharing** and confirm the Mac and the server are on the same network.\n2. Open **System Settings -\u003e General -\u003e Time Machine**.\n3. Click **Add Backup Disk**. TimeNest appears under the name you configured (default `TimeNest`).\n4. Select it. When prompted, enter the username and password you created in the TimeNest web UI, not your macOS password.\n5. Choose whether to encrypt the backup. Encryption is strongly recommended; TimeNest stores the backup as an opaque sparsebundle and cannot read your data either way.\n6. First backup will be slow (full copy). Subsequent backups are incremental and run hourly while the Mac is awake on the same LAN.\n\n## Configuration\n\nAll configuration is expressed through environment variables in `.env`. See [`.env.example`](.env.example) for the full list.\n\n| Variable                  | Default         | What it does                                                          |\n| :------------------------ | :-------------- | :-------------------------------------------------------------------- |\n| `BACKUP_PATH`             | `/mnt/timenest` | Absolute path to the external drive on the host                       |\n| `SERVER_NAME`             | `TimeNest`      | Name shown in Finder and Time Machine preferences                     |\n| `DEVICE_MODEL`            | `TimeCapsule8,119` | mDNS hardware model advertised to macOS (affects icon in Finder)   |\n| `ADMIN_USER`              | `admin`         | Web UI admin login                                                    |\n| `ADMIN_PASSWORD`          | -               | Required. Web UI admin password                                       |\n| `DEFAULT_QUOTA_GB`        | `500`           | Default per-user quota in gigabytes                                   |\n| `TIMEZONE`                | `UTC`           | TZ database name, e.g. `Europe/Berlin`                                |\n| `LOG_LEVEL`               | `INFO`          | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                   |\n| `ENABLE_METRICS`          | `true`          | Exposes Prometheus `/metrics` on the web UI port                      |\n| `SMB_INTERFACES`          | `eth0 wlan0`    | Interfaces Samba binds to. Leave blank for all                        |\n\n## Monitoring\n\n### Web dashboard\n\nThe dashboard at `http://\u003cserver\u003e:8080` shows per-user disk usage, last backup timestamp, current SMB sessions, and SMART health for every attached drive. It is a server-rendered HTML app (FastAPI + Jinja + htmx) so it works on any modern browser without a JS build.\n\n### Prometheus\n\nWhen `ENABLE_METRICS=true`, `/metrics` exposes:\n\n```\ntimenest_users_total\ntimenest_sessions_active\ntimenest_backup_bytes_total{user=\"...\"}\ntimenest_last_backup_timestamp_seconds{user=\"...\"}\ntimenest_disk_free_bytes{mount=\"...\"}\ntimenest_disk_smart_status{device=\"...\"}\n```\n\n### Alerts\n\nTimeNest can notify on backup failure or quota breach via:\n\n- SMTP email\n- Telegram bot (reuses [Claude Code's Telegram channel pattern](https://docs.anthropic.com/))\n- Generic webhook (Discord, Slack, ntfy.sh, Home Assistant)\n\nConfigure in the **Settings** page of the web UI.\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTime Machine does not see the share in Finder\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nBonjour (mDNS) packets must reach your Mac. Checklist:\n\n- Run `dns-sd -B _smb._tcp` on your Mac and confirm TimeNest is listed.\n- On Linux hosts, confirm the Avahi container is running with `--network host`. mDNS in bridge mode will not reach the LAN.\n- On Docker Desktop for Mac, enable host networking under Settings -\u003e Resources -\u003e Network.\n- If your LAN spans VLANs or Wi-Fi isolation is on, enable mDNS reflection on your router (UniFi, OPNsense, pfSense all support this).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTime Machine complains the disk does not support the required features\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nThis is almost always a missing `vfs_fruit` module or an old Samba build. Confirm Samba \u003e= 4.18 in the container with:\n\n```bash\ndocker compose exec samba smbd --version\n```\n\nThen check the generated `smb.conf`:\n\n```bash\ndocker compose exec samba cat /etc/samba/smb.conf | grep fruit\n```\n\nYou should see `fruit:time machine = yes`, `fruit:aapl = yes`, and `vfs objects = catia fruit streams_xattr`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBackups are slow\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nCommon causes, in order of likelihood:\n\n1. **Wi-Fi on the Mac.** A 5 GHz AC / AX link will sustain 30-80 MB/s. 2.4 GHz caps at 5-10 MB/s. Use gigabit Ethernet for the first full backup and swap to Wi-Fi afterwards.\n2. **USB 2 drive on the server.** USB 2 caps at 35 MB/s in practice. Use USB 3 or SATA.\n3. **Raspberry Pi 3 or earlier.** The single USB 2 bus is shared with Ethernet. Upgrade to Pi 4 or 5.\n4. **Filesystem overhead.** Samba + fruit on ext4 is fastest. Avoid exFAT and NTFS.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eThe share exists but Time Machine asks for a password I never set\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nmacOS caches SMB credentials in the Keychain. Open Keychain Access, search for the server name (e.g. `TimeNest`), delete the entry, and reconnect. You will be prompted for the new credentials.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eI want to migrate an existing Time Machine sparsebundle into TimeNest\u003c/b\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nCopy the `.sparsebundle` directory into `BACKUP_PATH/\u003cusername\u003e/` with `rsync -aHAX --info=progress2`, then claim it from the Mac:\n\n```bash\nsudo tmutil setdestination \"smb://\u003cuser\u003e@\u003cserver\u003e._smb._tcp.local/\u003cuser\u003e\"\n```\n\n\u003c/details\u003e\n\n## Performance benchmarks\n\nMeasured on a 100 GB full backup from a MacBook Pro M2 with `tmutil startbackup --block`.\n\n| Server                         | Drive                 | Link      | Backup time | Sustained MB/s |\n| :----------------------------- | :-------------------- | :-------- | ----------: | -------------: |\n| Mac mini M2, 16 GB             | USB 3.2 NVMe 1 TB     | Gigabit   |     18m 42s |             89 |\n| Raspberry Pi 5, 8 GB           | USB 3 NVMe 1 TB       | Gigabit   |     21m 05s |             79 |\n| Raspberry Pi 4, 4 GB           | USB 3 SATA SSD 1 TB   | Gigabit   |     27m 30s |             61 |\n| Intel NUC 10, 16 GB            | SATA HDD 4 TB         | Gigabit   |     34m 10s |             49 |\n| Raspberry Pi 4, 4 GB           | USB 2 HDD 2 TB        | Gigabit   |  1h 02m 15s |             27 |\n\n## Projects and products TimeNest replaces\n\nIf you arrived here searching for any of the following, this is the project you want. TimeNest is an actively maintained, open-source replacement.\n\n- **Apple Time Capsule** (discontinued 2018) - TimeNest is the functional successor. Drop-in Bonjour advertisement as a `TimeCapsule8,119` so Finder, System Settings, and Migration Assistant all recognize it.\n- **Apple AirPort Time Capsule** - Same use case, newer hardware. Use any USB 3 SSD instead of the built-in drive.\n- **iCloud Backup for Mac** - iCloud does not back up your full disk. TimeNest does.\n- **Backblaze for Mac** - Fine product, but a paid cloud service that charges per Mac. TimeNest is a one-time capital expense (a Raspberry Pi and an SSD).\n- **Synology Time Machine share** - Works great if you already own a Synology. TimeNest is a fit when a full NAS is overkill.\n- **TrueNAS / OpenMediaVault Time Machine plugin** - Again, great if you run one of those. TimeNest is 1/100th the install footprint.\n- **`dperson/samba` + hand-rolled Avahi config** - What most Reddit threads end at. TimeNest is that, but with per-user quotas, a web UI, SMART, metrics, multi-arch images, and a tested `smb.conf`.\n\nEqually useful as a **Mac mini backup server**, a **Raspberry Pi Time Machine server**, a **homelab SMB backup target**, or a **small-office shared Time Machine drive**.\n\n## Security notes\n\n- TimeNest exposes Samba on TCP/445 and the web UI on TCP/8080. Do not port-forward either to the internet. For remote backups use Tailscale, WireGuard, or a VPN.\n- SMB signing is enabled by default. SMB1 is disabled. TLS on the web UI is handled via a reverse proxy (a Caddy example is provided in `docs/`).\n- TimeNest never reads backup contents. Time Machine sparsebundles can be fully encrypted at creation time on the Mac side and you are encouraged to do so.\n- Admin credentials are stored as bcrypt hashes under `./data/auth.db`. Samba users are stored in Samba's native `passdb.tdb`.\n\n### Verifying release artifacts\n\nAll published Docker images are signed with [cosign](https://github.com/sigstore/cosign) using keyless GitHub OIDC, and the macOS `.pkg` is signed with a Developer ID Installer certificate and notarized by Apple. Verify before running:\n\n```bash\n# Docker images\ncosign verify ghcr.io/momenbasel/timenest-samba:latest \\\n    --certificate-identity-regexp 'https://github.com/momenbasel/timenest/' \\\n    --certificate-oidc-issuer https://token.actions.githubusercontent.com\n\n# macOS .pkg (after downloading from a GitHub release)\npkgutil --check-signature TimeNest-*.pkg\nspctl --assess --type install --verbose TimeNest-*.pkg\n```\n\n## Roadmap\n\n- [x] SMB3 Time Machine share with Bonjour discovery\n- [x] Per-user quotas and multi-user isolation\n- [x] Web UI with live disk and session status\n- [x] Prometheus metrics\n- [ ] SMTP / Telegram / webhook alerts (v0.3)\n- [ ] Multi-drive RAID1 and RAID5 wizard via `mdadm` (v0.4)\n- [ ] Encrypted off-site replication to S3 / Backblaze B2 (v0.5)\n- [ ] Web-based sparsebundle browser with restore (v0.6)\n- [ ] iOS / iPadOS backup target via SMB (v0.7, experimental)\n\n## FAQ\n\n**Is this legal?** Yes. TimeNest uses Samba's standard `vfs_fruit` module. There is no Apple code, no reverse-engineered protocol, and no trademark use.\n\n**Will Apple break this in a future macOS release?** Apple has endorsed SMB3 + `vfs_fruit` as the supported non-Apple Time Machine target since Samba merged the module in 2017. The last regression was fixed in macOS 13.4. TimeNest tracks Samba upstream closely.\n\n**Can I use this for an office of 20 Macs?** Yes. Benchmarks above scale linearly with drive and network bandwidth. Plan roughly 1 TB of storage per Mac for a 90-day retention window.\n\n**Can I put this behind Nextcloud / Synology / TrueNAS?** Those products already ship their own Time Machine support. TimeNest is for the case where you want a minimal, scriptable, self-contained stack on generic hardware.\n\n**Does it work with macOS Ventura, Sonoma, Sequoia, and later?** Yes as a *client*. Any modern Mac can back up to a TimeNest server running on Linux or a Raspberry Pi. The first backup on Sequoia sometimes requires enabling *Show Legacy File Sharing* once, see [Troubleshooting](#troubleshooting).\n\n**Can I run the TimeNest server itself on a Mac mini?** Technically yes, practically no. macOS already owns `:445` and `:5353` for its own File Sharing and Bonjour stacks, which TimeNest needs. Use native macOS File Sharing on the Mac mini and run TimeNest on a Raspberry Pi or Linux box instead. See [Running on a Mac mini](#running-on-a-mac-mini-read-this-first).\n\n**Does it work on Windows hosts?** No. Samba + vfs_fruit + Avahi is a Linux stack. WSL2 works but networking is awkward; a spare Pi is easier.\n\n## Contributing\n\nIssues and pull requests are welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for coding style, test harness, and the release process. The project is MIT licensed and intended to stay small, sharp, and dependency-light.\n\n## License\n\nMIT. See [`LICENSE`](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\u003cbr\u003e\n\u003csub\u003eBuilt because living out of a dangling USB cable is not a backup strategy.\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmomenbasel%2Ftimenest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmomenbasel%2Ftimenest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmomenbasel%2Ftimenest/lists"}