Install
Download the latest build for your platform below, or pick any version on the Releases page. Once installed, TableCraft updates itself.
| Platform | Download |
|---|---|
| macOS (Apple silicon) | TableCraft-arm64.dmg |
| macOS (Intel) | TableCraft-x64.dmg |
| Windows x64 | TableCraft-x64.exe |
| Linux x64 | TableCraft-x86_64.AppImage |
First launch
Section titled “First launch”The builds are not signed with a paid certificate, so the first launch needs one extra step:
- macOS: see Running the unsigned macOS app below.
- Windows: SmartScreen says Windows protected your PC; click More info, then Run anyway.
- Linux: make the AppImage executable with
chmod +x TableCraft-*.AppImageand run it.
To make sure a download arrived intact, check it against SHA256SUMS.
Check a download
Section titled “Check a download”Every release also carries SHA256SUMS, the SHA-256 of each file on the release
(decision 135).
Check a download on macOS or Linux
Section titled “Check a download on macOS or Linux”-
Download
SHA256SUMSinto the folder that holds the installer. -
From that folder, run:
Terminal window # macOSshasum -a 256 -c --ignore-missing SHA256SUMS# Linuxsha256sum -c --ignore-missing SHA256SUMS
Each file you downloaded prints OK. Anything else means the download is damaged, so delete it and
download it again.
Check a download on Windows
Section titled “Check a download on Windows”Compare the output of this PowerShell command with the installer’s line in SHA256SUMS:
(Get-FileHash .\TableCraft-<version>-x64.exe -Algorithm SHA256).Hash.ToLower()The checksums prove a download is intact, not who made it. Updates the app installs itself are checked against a signed manifest instead (Updates).
Running the unsigned macOS app
Section titled “Running the unsigned macOS app”The DMGs are ad-hoc signed rather than notarized, because a Developer ID belongs to whoever ships the build and not to this repository (decision 033).
macOS quarantines anything a browser downloaded, and Gatekeeper refuses to open a quarantined app it cannot verify. Depending on the macOS version it says either “TableCraft” Not Opened. Apple could not verify “TableCraft” is free of malware… or “TableCraft” is damaged and can’t be opened. The app is not damaged; only the download attribute is in the way.
Pick the DMG that matches your Mac: arm64 for Apple silicon, x64 for Intel. An app you build
yourself with bun run desktop:package was never downloaded, so it carries no quarantine and opens
directly.
Clear the quarantine attribute
Section titled “Clear the quarantine attribute”-
Open the DMG and drag
TableCraft.appto/Applications. -
Clear the attribute the download added:
Terminal window xattr -dr com.apple.quarantine /Applications/TableCraft.app -
Open TableCraft as usual.
Nothing inside the app changes. Only that attribute is removed, and only once per download.
Open it from System Settings
Section titled “Open it from System Settings”If you would rather not use the terminal and macOS showed Not Opened:
- Click Done.
- Open System Settings → Privacy & Security and scroll to Security.
- Click Open Anyway next to the message about TableCraft.
- Confirm with your password.
That button appears only for an hour or so after the refused launch. The damaged message offers no
such button; use xattr.
Updates
Section titled “Updates”A little after launch, and every 2 hours while it runs, TableCraft asks GitHub whether a newer release is out. When there is one, an Update button appears in the main toolbar, just left of Settings. Nothing is downloaded until you click it and choose Download.
Install an update
Section titled “Install an update”- Click Update in the main toolbar.
- Choose Download. The button shows the progress.
- Click Restart to Update.
TableCraft quits, puts the new version in place of the old one and opens again. On Windows the update runs the installer silently and reopens TableCraft; on Linux it replaces the AppImage you started.
Skip This Version hides that release until a newer one comes out. Later closes the popover and leaves the button where it is.
Choose when and what to update
Section titled “Choose when and what to update”- Help → Check for Updates… asks right away, and says so when you are up to date.
- Turn off Check for updates automatically in Settings → Advanced to check only from Help.
- Turn on Get beta versions in Settings → Advanced to be offered betas (
1.16.0-beta.1) ahead of each release, and pre-release plugins with them. A beta you install by hand has it on already. Turning it off never downgrades: you keep the beta until a newer release is out.
Every release is described by a manifest signed with the project’s key. TableCraft refuses a manifest whose signature does not verify and a download whose SHA-256 does not match it, deletes what it fetched and tells you why (decision 044).
Let the app replace itself on macOS
Section titled “Let the app replace itself on macOS”On macOS the app replaces itself only from a folder you can write to, such as /Applications. Run
from the disk image or from a folder macOS moved it to, the button explains what to do and links to
the release instead.
The same goes when macOS’s App Management protection would stop the app from replacing itself. Allow TableCraft in System Settings → Privacy & Security → App Management, or install the release by hand. If a Restart to Update still leaves the old version in place, the button says why on the next launch instead of offering the update as if new.
Answer the keychain prompt after an update
Section titled “Answer the keychain prompt after an update”macOS asks for your keychain password after every update. The app is ad-hoc signed, so each version looks like a different app to the keychain. Before the new version opens, macOS asks for your login keychain password to let it read “TableCraft Safe Storage”. Enter it and choose Always Allow.
Deny leaves passwords saved Forever unreadable, so connecting asks for them, until you allow it at a later launch. Installing a new DMG by hand asks the same.
Update from v0.1.0
Section titled “Update from v0.1.0”Release v0.1.0 predates updates. Install the next release by hand once, and it keeps itself
current from then on.
Build from source
Section titled “Build from source”You need Bun and Node; CONTRIBUTING.md names the versions and the rest of the toolchain.
bun installbun run desktop # build and launch the appbun run desktop:package # an installer for this machine in packages/desktop/release/