go-haystack: Build Find My Beacons with Go and TinyGo

go-haystack's Find My Beacon Model

go-haystack is aimed at developers and makers who want personal Bluetooth devices to appear through Apple's Find My network. The repository describes it as a way to track devices using OpenHaystack and Macless-Haystack, with tools written in Go and TinyGo. Its scope is not a conventional GPS receiver. The project focuses on Bluetooth beacon advertisements and a local scanning workflow.

The main use case is custom hardware. The README documents Adafruit Bluefruit boards using nRF SoftDevice, BBC Microbit, Seeed Studio XIAO nRF52840, Nordic Semiconductor boards using SoftDevice, ESP32 boards using NINA-FW or their integrated radio, and RP2040 Pico-W boards using the CYW43439 co-processor. The documented ESP32-C3 and ESP32-S3 targets are `xiao-esp32c3`, `xiao-esp32s3`, `esp32c3-supermini`, `esp32s3-supermini`, `esp32c3-generic`, `esp32s3-generic`, `qtpy-esp32c3`, and `m5stamp-c3`. Those targets require TinyGo 0.42 or later.

That support list is a useful decision boundary, but it is not a promise that every Bluetooth board will work. The project is better suited to a controlled build where the hardware radio, memory, flashing path, and TinyGo target are known than to an unplanned device rollout. The README does not describe a mobile app or a standalone hosted tracking service in this repository. Macless-Haystack provides the associated endpoint setup, while go-haystack supplies the key, beacon, flash, and scanning tools.

Beacon Keys and Advertisement Rotation

A device is represented by generated key material and beacon configuration. According to the README, the `haystack keys` command creates a `.keys` file containing advertisement keys and a `.json` configuration file for Haystack. The default command generates a set of 12 keys, and the `-keys` option selects a different number. These files are therefore not optional implementation details. They connect the hardware advertisement to the device registration workflow.

The Linux beacon path is short and concrete. The firmware code is located in the `firmware` directory, and the beacon receives keys as its first argument, separated by commas. Its second argument is the time used on each key. The README gives this form:

cd firmware
go run . KEY1,KEY2,KEY3 5m

The repository says to use the advertisement keys from the device's `.keys` file. The same firmware source is also used for embedded Linux, so a Raspberry Pi or another Bluetooth-capable Linux system can run the beacon without a dedicated microcontroller. The README does not specify the behavior when a key expires, when all keys have been consumed, or when the clock is unavailable. It also does not document a production service unit or automatic restart configuration. Those are operational details that remain outside the project's visible instructions.

For a first use, generating keys and starting the Linux beacon provides a way to exercise the core path. For embedded hardware, the README says to flash firmware with a TinyGo target and the device name. That makes the key files a dependency of both software-based and hardware-based deployments, and calls for careful protection because replacing them may change which device the beacon represents.

Installing the CLI and Macless-Haystack Services

The documented installation has two separate parts. The Macless-Haystack side uses Docker services, and go-haystack itself is installed with Go. The README first requires an Apple ID with 2FA enabled. It specifically says that only SMS or text message as the second factor is supported. This is a direct setup constraint, not a general statement about Apple authentication.

Start `anisette-v3-server` with the following commands:

docker network create mh-network
docker run -d --restart always --name anisette -p 6969:6969 --volume anisette-v3_data:/home/Alcoholic/.config/anisette-v3 --network mh-network dadoum/anisette-v3-server

Then start Macless-Haystack in interactive mode:

docker run -it --restart unless-stopped --name macless-haystack -p 6176:6176 --volume mh_data:/app/endpoint/data --network mh-network christld/macless-haystack

The interactive process asks for the Apple ID, password, and 2FA. The README identifies the message `serving at port 6176 over HTTP` as confirmation that setup is complete. Stop that interactive process with Ctrl-C after configuration, then restart the named container:

docker restart macless-haystack

Install the go-haystack command after the service setup:

go install github.com/hybridgroup/go-haystack/cmd/haystack@latest

This installation path assumes Go is available and that the command's binary directory is on the user's PATH. The README does not document a package manager installation, a Windows-specific installation procedure, or how to configure a non-default PATH. It also does not provide rollback steps for Docker volumes or account authentication. Those omissions matter when an operator needs a controlled upgrade or recovery procedure.

Scanning, Flashing, and TinyScan Workflows

The CLI provides a first local operation through `haystack scan`, which the README says returns local Bluetooth devices within range. The output format includes a Bluetooth address, a numeric value, a long device identifier, and a battery field such as `battery full`. This is a local scan. The repository does not state that the command provides historical location data or a substitute for every feature of Apple's Find My application.

Adding a device has two explicit stages. First generate the files:

haystack keys DEVICENAME

The README says the files are named `DEVICENAME.keys` and `DEVICENAME.json`. It then gives this flashing example:

haystack flash DEVICENAME nano-rp2040

The command compiles the firmware using TinyGo and flashes it to the device. For boards using ESP32-C3 or ESP32-S3 radios, the listed targets and TinyGo 0.42 requirement are stated earlier, but the visible instructions do not show every corresponding flash command.

TinyScan is a separate local scanner. The README says it can run on several microcontroller boards with Bluetooth and miniature displays, including boards from Adafruit and Pimoroni. Its source is in the `tinyscan` directory. A user can flash it with device names and use `-onlymine` to hide beacons that do not belong to the user's devices. The README gives:

haystack flashscan clue blackgopher redgopher

These commands show that go-haystack combines remote registration, firmware provisioning, local scanning, and an optional display-oriented scanner. The repository layout separates these concerns into `cmd/`, `firmware/`, and `tinyscan/`, which helps explain the project as a toolkit rather than one application.

Maintenance, Licensing, and Practical Limits

The repository is not archived, and its last push was on 2026-10-13. The project uses Go 1.25.0 in `go.mod` and depends on current TinyGo packages, including `tinygo.org/x/bluetooth`, `tinygo.org/x/drivers`, `tinygo.org/x/tinyfont`, and `tinygo.org/x/tinyterm`. There are no GitHub releases listed. Consequently, the repository metadata gives evidence of recent source activity but not a formal release cadence. An adopter should treat the default branch and its dependency versions as part of the upgrade decision rather than assuming a versioned support policy.

The stated license is MIT. That license permits use, modification, distribution, and sublicensing subject to its conditions, including preservation of the copyright and license notice. This is a source-level statement, not legal advice about particular hardware, network services, or deployment arrangements. The project also relies on Apple authentication and third-party components, so the repository's MIT license does not automatically settle the terms of every related service or dependency.

A genuine limitation is the dependence on external account and endpoint setup. The visible instructions require an Apple ID with SMS or text-message 2FA, `anisette-v3-server`, and `macless-haystack`. The README does not explain how those components behave when credentials expire, when the endpoint is unavailable, or when a beacon's advertisement keys need rotation. It also does not provide rollback documentation, a documented backup procedure for `.keys` files, or a release migration guide.

go-haystack gives makers control over beacon hardware and offers Linux and TinyGo paths, but adds device compatibility, flashing, key management, and service configuration work. It is the better fit when custom hardware matters and the documented constraints are acceptable.

Editorial conclusion

Adopt go-haystack if you want to build custom Find My beacons and accept the setup burden of Apple authentication, Docker services, generated key files, and supported Bluetooth hardware. Do not adopt it as a general-purpose Bluetooth tracker without first checking the documented board targets and TinyGo requirements. Verify the generated `.keys` and `.json` files, the flashed target, and the Macless-Haystack endpoint before relying on a beacon for tracking.

Frequently asked questions

Official sources

1. hybridgroup/go-haystack on GitHub
2. Issues
3. License: MIT
4. README