TimeCapsuleSMB puts a modern Samba on an Apple Time Capsule

The problem is Apple's removal of SMB1 and AFP

Apple AirPort Time Capsules only support AFP and SMB1 natively, and Apple has removed AFP support in macOS 27 and removed SMB1 support from macOS a long time ago. TimeCapsuleSMB is a Samba setup that runs directly on the Time Capsule itself and makes it compatible with macOS 27 and later computers.

The result is that a computer running macOS 27 or later can connect to the Time Capsule as a network share and use it for Time Machine backups, and your old backup automatically works after updating with no wipe required. That last point is the commercially important one. A Time Capsule is usually someone's only backup of years of family photographs, and the usual advice when a platform drops the old protocol is to buy new hardware and migrate, or to lose access to the archive.

The project has two parts. The first is a fork of Samba 4, modified to work on the Apple Time Capsule, and the second is the installers for the Samba binary, via terminal or the macOS GUI app.

What runs on the device is its own Samba 4.25 server, and it advertises SMB over Bonjour, so it shows up automatically in the Network folder on macOS. You can open Finder or use Connect to Server, and you can use a normal SMB URL without relying on Apple's legacy SMB1 stack. The disk can also be used for Time Machine backups.

The project's ambition is stated in plain terms: you should get the full Apple It just works experience reproduced. And it goes further than that, because the device uses mDNS and Bonjour, so it works even if its IP address is not static and gets changed, and it will show up automatically in the Time Machine section of the Settings app. The device's IP changing is a genuine annoyance with original Time Capsules, and Bonjour advertisement removes it.

Deploy writes to flash and to a hidden folder on the disk

The mechanics of the install are described precisely enough that the failure modes are predictable, which is valuable for something that modifies a device you cannot easily reflash.

The Install or deploy script installs files in /mnt/Flash on the Time Capsule, plus a .samba4 folder on the root of the hard drive. The uninstall script removes those managed files and can optionally reboot the device afterward. The split between flash and disk is what determines which devices the project supports.

On boot behaviour, NetBSD 6 devices automatically start the server. Older NetBSD 4 devices can flash the firmware to add a boot hook, which allows it to start Samba on reboot, and if you do not flash the boot hook then Samba will not start automatically on an older Time Capsule. The alternative is to choose to do a manual activate after every reboot, if you do not want to flash the firmware. The README also notes a Persistent NetBSD4 Boot Hook section on the device's maintenance page for generation 1 to 4 devices.

Firmware flashing is the part that deserves the most care, and the project is upfront that it is optional with a manual alternative. That is the right way to present it, since a firmware flash is the one step here that can make a device unbootable if it goes wrong.

The authentication model is unusual and worth understanding. It accepts any user as the username, and the Samba password is the current Time Capsule device password. At boot the device reads its live AirPort syPW value and generates the Samba password file in RAM, so a device password change is picked up after reboot. Guest access is disabled.

So there is one credential, the device password you already have, and it stays in sync automatically. The trade-off is that the username is not a real identity, which means per-user file ownership and permissions on the share are not something you can rely on for access control between users.

AirPort Extreme works only with a hard drive, and the binaries are prebuilt

The device support is narrower than the name suggests, and the README is explicit about the boundary.

AirPort Extreme devices are not officially supported. Unofficially, they work fine. The catch is that this is installed to the hard drive, so it will not work for an AirPort Extreme without a hard drive, since there is not enough space to store the binaries on the flash memory.

That constraint is the whole reason the project targets the Time Capsule rather than the Extreme. The Time Capsule shipped with a hard drive, the Extreme often did not, and the binaries are large enough that flash alone is not viable.

The binaries themselves are checked in rather than built by the user. The working binaries are saved in the repository under bin/, and the normal installer uses those checked-in files directly, so you do not need to build Samba yourself. There are three variants, chosen by the device's architecture: /bin/samba4/smbd for NetBSD 6 devices, /bin/samba4-netbsd4le/smbd for NetBSD 4 little-endian devices, and /bin/samba4-netbsd4be/smbd for NetBSD 4 big-endian devices. The binaries are statically compiled.

If you want to rebuild smbd yourself, the README says to run the scripts in build/ on a NetBSD machine, which is a reasonable constraint given that the target is a NetBSD system and the Samba fork has to be cross-compiled for it.

The AirPort Extreme situation is the general shape of the project. The hardware is a closed platform with two operating system lineages, and the compatibility work is real engineering rather than configuration. The fact that a fork of Samba 4 exists at all, rather than a script, is a measure of how much had to change to make a modern SMB server run on it.

The tcapsule CLI and the macOS app cover different halves of the setup

There are two front ends, and the README explains the split by platform rather than by preference.

On Linux you must use the Python CLI version. On an Intel Mac the CLI can deploy without Homebrew, but Homebrew no longer builds smbclient for Intel, so doctor cannot run its SMB checks there, and the universal macOS app includes everything. The requirements for the Python setup are Python 3.9 or newer, smbclient installed locally for doctor, and Homebrew for macOS users, which requires an Apple Silicon computer.

The Makefile spells out the workflow with four steps:

./tcapsule bootstrap
.venv/bin/tcapsule configure
.venv/bin/tcapsule deploy
.venv/bin/tcapsule doctor

The other Makefile targets are the development ones: make venv creates the local virtualenv, make install installs the Python dependencies when the inputs change, make lint runs Ruff against the sources and tests, make test runs the C compile checks and the pytest suite, make test-parallel runs pytest-xdist, make coverage produces a coverage report, make coverage-html writes an HTML report to htmlcov/, make coverage-native reports native C coverage with LLVM tools, make test-c compile-checks the unified native service image, make test-swift runs the macOS app's Swift tests in parallel, make discover runs the discovery command, and make set-ssh is the advanced SSH toggle helper.

The presence of Swift tests, a native C service and pytest in the same Makefile is a good sign about the project's structure. The C side is the patched Samba that runs on the device, the Python is the installer that ships it, and the Swift is the macOS app. The three are tested separately, which is the right way to test a project that spans three languages and two operating systems.

The macOS app flow is a straightforward wizard. You download the release, unzip and run the app, grant Local Network permission in System Settings and reopen the app, click Add Device and select it, enter the device password and save, wait for the app to enable SSH, then use the Install / Update tab and click Install / Update Samba to deploy.

The troubleshooting notes in the README are unusually concrete. If deploying fails, remove the saved device and add it again, because it sometimes takes more than one deploy to copy all the files over. And there are reports the device may reset during a deploy, with a linked issue, though the README is clear that you should not be worried if the device resets since your data on the hard drive is safe and only the Apple configuration settings such as the WiFi name and password will be reset.

The environment file shows the tunables and the SSH compatibility flags

The .env.example file is the clearest documentation of the deployment's internal settings, and it is worth reading before a first run.

The file is described as local user and device configuration, to be copied or regenerated with tcapsule configure. It holds TC_HOST, which is a root SSH target such as [email protected], and TC_PASSWORD, and then TC_SSH_OPTS with a specific set of options:

TC_SSH_OPTS='-o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedAlgorithms=+ssh-rsa -o KexAlgorithms=+diffie-hellman-group14-sha1 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

That line explains a lot about the target. ssh-rsa host keys and the diffie-hellman-group14-sha1 key exchange are old algorithms that modern OpenSSH clients disable by default, and the flags re-enable them because the Time Capsule's NetBSD SSH stack offers nothing newer. StrictHostKeyChecking=no with UserKnownHostsFile=/dev/null means the device's key is not verified, which is a consequence of connecting to a device whose key changes when it is factory reset.

The behavioural switches are also here. TC_INTERNAL_SHARE_USE_DISK_ROOT is false by default, TC_SMB_BROWSE_COMPATIBILITY is false, TC_ANY_PROTOCOL is false, and TC_VFS_AIO_FORK_DISABLED is false. The drive timer settings are applied to built-in ATA disks during runtime startup, with TC_ATA_IDLE_SECONDS defaulting to 300 and TC_ATA_STANDBY left blank to avoid changing standby, or set to 0 to disable it.

The ATA timer controls are a detail that shows how much of the work is about the device rather than about SMB. A Time Capsule's disk spinning down is a sensible power saving on a shelf, and it is a problem for a backup destination, so the runtime startup can adjust the idle timer on the built-in ATA disks.

The Python dependencies are minimal and tell you what the installer does: zeroconf for Bonjour discovery, ifaddr for enumerating local network interfaces, pycryptodome for the cryptography, and zopfli for compression.

GPL-3.0, frequent releases, and a project that keeps its own documentation

The licence is GPL-3.0, and the pyproject.toml states it as GPL-3.0-only with the LICENSE file listed in license-files, and the LICENSE file in the repository is the authoritative text. This is a licensing statement rather than legal advice, and it is worth noting that a Samba fork is GPL by nature, so the licensing of the whole project is unsurprising.

The release cadence is fast. v3.5.0 on 2026-10-15, v3.4.0 on 2026-10-09 and v3.3.1 on 2026-10-07. The repository is not archived, and the version in pyproject.toml is 3.5.0, matching the latest tag. The classifier says Development Status:: 4 - Beta, which is a fair self-description.

The repository layout is that of a project with a real documentation habit. Alongside the README there is DETAIL.md, FAQ.md, RELEASE.md, SECURITY.md, CODE_OF_CONDUCT.md and CONTRIBUTING.md, plus a CI workflow badge at the top of the README.

Having FAQ.md as a separate file is a small thing that says a lot, because the FAQ is the document people actually read when a deploy goes wrong on a device with no display and no documentation from Apple. The same reasoning applies to SECURITY.md, since a project that asks people to flash firmware onto their backup hardware should say how to report a problem with the deploy tooling.

The project description says hacking the Apple AirPort Time Capsule to run modern Samba, and the topics confirm the surface: airport-time-capsule, bonjour, macos, netbsd, samba, smb3, time-capsule and time-machine. The smb3 topic is the technical heart of it, and the netbsd topic is the platform constraint that everything else follows from.

Editorial conclusion

Adopt TimeCapsuleSMB if you own an Apple AirPort Time Capsule with a working hard drive and want it to keep serving as a network share and Time Machine destination after Apple's SMB1 removal. Do not adopt it for an AirPort Extreme without a hard drive, since the binaries are installed to the disk and there is not enough room on the flash memory. Before you start, confirm your Mac and the device are on the same local network, have the device password ready, and note that a deploy can reset the Apple configuration on the device, though the data on the hard drive is safe.

Frequently asked questions

Official sources

1. jamesyc/TimeCapsuleSMB on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases