Gearsmith

Beta - a simple self-hosted gear tracker for guitarists. Keep your guitars, amps, pedals, picks, and strings in one place, track how old each guitar's strings are, group gear into sets (boards and rigs), and save the exact settings each song needs. One Docker container, SQLite storage, no subscriptions, no cloud account - your data stays on your box.

Screenshots

Gear collection - the whole stable at a glance, with string age chips on every guitar.

Gear detail - specs, string status, and photos for one instrument.

Sets and pedalboards - a board's layout with chain order and total power draw.

Preset - a reusable saved tone: the signal chain with every knob setting, plus setting photos of the real board.

Songs - the per-song recall sheet: tuning, capo, key, tempo, and the exact settings for each section.

Photo overlay - tap any setting photo for the full view; close with the X, the backdrop, or Esc.

Mobile collection - the gear grid with string chips on a phone.

Mobile preset - the full signal chain with every setting on a phone.

Mobile photo overlay - the full-size setting photo on a phone.

How the pieces fit together

• My Boards (sets, boards and setups) are your physical gear groupings, such as a pedalboard or compact rig. A set records which gear is in it and the order of its signal chain. It does not store the knob positions for each song.
• Presets (saved sounds) store a reusable tone: a pedal and amp chain, knob settings and modeler patches. Add an artist name to group a preset under Songs > Artists. One preset can be linked to several songs; editing it updates the sound those songs recall. Artist sounds live under Songs > Artists; the old standalone Presets list is gone. Existing preset detail links and API routes still work.
• Songs record the song's title, artist, tuning, notes and rig. A song can link one or more presets for shared sounds (for example, one artist sound across several songs) or hold its own settings. Copy into song makes an independent copy and stops following that preset; the original preset stays intact. Use the linked form when songs should change together and a copy when one needs different settings.

Boards, presets and songs are separate views of the same gear, not duplicate gear inventory. Deleting a set does not delete its gear. Deleting a preset that songs use removes their live link, so copy settings into those songs first if you need to keep their sound.

What it does

• Gear inventory - guitars, amps, pedals, picks, and strings, each with the spec fields that matter:
  • Guitars: finish, pickups, nut, scale length, tuning, string gauge, mods, serial, status (home / at the luthier / lent out)
  • Amps: wattage, speaker, tubes, serial
  • Pedals: voltage, current draw (mA), polarity, true bypass vs buffered
  • Picks: thickness, material, how many you've got
  • Strings: brand, gauge (10-46, 9-42...), type (electric, acoustic, classical, bass), material, strings per set, sets per pack
  • Photos on everything, purchase date, price paid and current value, notes
• Strings on each guitar - every guitar can pick the strings it uses from your Strings section, and each strings page lists the guitars using it. When you log a restring, pick the strings from a list and the brand and gauge fill in (or just type them). Deleting a strings item keeps the brand and gauge on old restring entries.
• String stock countdown - a strings item can track how many unopened sets you have. Logging a restring with those strings takes one set off the count automatically; the card and page show the count and flag "1 set left" and "Out of sets". Adjust the count by hand on the strings page (or leave it untracked).
• Maintenance log - every item keeps a service history: date, category (setup, tubes, fret work, repair, other) and a note. Add, edit and delete entries on the item's page.
• Manual links - each item can carry a link to its manual, shown as a Manual button on the item's page. Links only; Gearsmith never stores the files.
• Built-in tuner - an A440 tuner in its own tab. Pick a tuning - standard, half step down, full step down (D standard), drop D, drop C#, drop C, drop B, open G, open D, open E, DADGAD, or plain chromatic - and it shows the target note for each string, reads against the nearest one, and says tune up or down. Your last tuning is remembered on that device. It runs fully in your browser with the Web Audio API - the mic signal never leaves your device, and the tab can be hidden in Settings > Features.
• Backup export - Settings > Backup downloads the whole collection as one JSON file: gear, photos (stored names and links), sets, songs, presets, setlists, restrings, maintenance entries and string counts.
• Restring tracking - log a restring (brand, gauge, date) and each guitar gets a "strings: N days" chip that turns yellow as the interval nears and red when it's overdue. Every guitar has its own restring interval.
• Previous and next - every gear page has previous/next buttons (and the left/right arrow keys on a keyboard) to step through your gear without going back to the list. They follow the Gear page order - by section, favorites first, then by name - and respect whatever search or filter you had on. On a phone they shrink to two small arrows with an "N of M" count above the title.
• Price paid and value - every item can carry what you paid and what it's worth today (plain USD, both optional). The item page shows the gain or loss, and the Gear page shows a collection total: overall value, what you paid, and how much you're up or down. Items with no value set count at what you paid; items with neither aren't counted. The Want list gets its own total (what it would cost to buy everything on it) and never counts toward the collection, and the Sold view totals what you sold for. Values stay private: share pages never show them. Don't want the numbers on screen? Turn off Collection value in Settings > Features: the totals and the prices on item pages and badges go away, and the fields stay in the edit form so you can keep filling them in.
• Favorites - tap the star on any card or on the gear page to mark a favorite. Favorites sit at the top of their section, and the "Favorites only" button on the Gear page hides everything else (it remembers your choice on that device).
• Songs - a recall sheet for every song you play: tuning, capo, key, BPM, the guitar and amp, and the knob settings on each pedal and amp in the chain (on, off, or toggled mid-song). Knob positions are free text, so "2:00", "noon", "max", and "7.5" all work. Multi-effects units and modelers (Helix, Quad Cortex, Kemper, and so on) get patch pointers instead: patch number and name, scenes, MIDI notes, and an optional list of effect blocks. Add photos of your board or a handwritten sheet, or attach photos to individual rig settings. Each gear page lists the songs that use it.
• Artist sounds (presets) - attach photos of a full rig to a named tone, visible as a thumbnail under Artists and opening full size in an overlay on its page. Hide setting photos in Settings > Features without deleting them. Save a tone once (the chain, knob settings, patches, and amp) under a name like "Classic crunch" or "Ambient clean", then use it in any song. Presets stay linked: change the preset and every song using it shows the new settings. A song can use several presets with labels ("Verse", "Solo"), plus its own settings on top. Turn a song's chain into a preset with Save as preset, or use Copy into song when one song needs its own tweaked version. Preset cards show the chain at a glance, and a rig in parentheses at the end of the name, like "Treaty Oak (Ampero Mini)", shows as a small tag under the title.
• Setlists - line up songs for a practice session or a gig in the Songs tab's Setlists view. Each song in the run shows its linked presets and knob settings right next to it, so one page covers the whole session, and the list flags when the next song needs a retune or a different guitar. Reorder by dragging or with the arrows; a song can appear more than once. Deleting a setlist keeps the songs.
• Artists - the Songs tab has an Artists view that groups your songs and presets by artist. Presets start collapsed for each artist; open only the group you want. You can attach a setting photo to an individual pedal or amp on a preset, in addition to the whole-preset photo. Grouping ignores capitalization and extra spaces.
• Song tab links - save an optional HTTP(S) tab URL in a song's edit form. Its Open song tab link sits with the song's rig and opens in a new tab; it does not copy the tab into Gearsmith or fetch it for you. Turn off Song tab links in Settings > Features to hide the links without deleting saved URLs. Only open links from sources you trust.
• Visual knob dials - song and artist-sound rig cards draw clock settings (9:30, noon, 1:00) as dials with the exact value beside them. Numeric 0-10 guitar/amp controls use a schematic sweep, not a clock. Open-ended settings such as "around unity" and "to room volume" stay text. Turn off Visual knob dials in Settings > Features for text-only cards. Dials are illustrative, not calibrated hardware diagrams.
• Controls live on the gear - each guitar, amp or pedal lists its knobs and switches (Gain, Tone, Level...) in panel order under Controls on its page, editable with the arrows there. Songs and artist sounds reference those controls and only store the settings: the editor shows the item's controls in order and you fill in the values. Edit a control's name or order once on the item and every song and preset follows. Each control can also keep your everyday setting ("Gain: 6"), which new songs and presets start from. Gear without a controls list still takes free-form knob names per song, with arrows to order them, and a Save as controls button promotes what you typed to the item in one tap. On first run after upgrading, Gearsmith builds each item's controls from the knob names your songs and presets already use (most common order, values untouched) and backs up the database first. Mark a pedal as a modeler to track patches for it instead of knobs.
• Want and Sold lists - gear you're after (with a target price) and gear you've sold (with sale date and price) live in their own views next to what you own. Sold gear is dimmed and never shows up in the restring due list or notifications.
• Share links - make a read-only link to one piece of gear or a whole set to send to a buyer, a tech, or a friend. Links use a random token, can expire (7, 30, or 90 days, or never), can show as a QR code for sharing in person, and can be turned off or replaced at any time. Shared pages hide serial numbers and prices, show no links back into your app, and tell search engines not to index them.
• My Boards - group gear into rigs: a pedalboard, a gig rig, a recording chain. Gear can live in several sets or none. Each set has its own page with its gear, notes and share link.
• Pedalboard layout - a set's page lays its pedals out as a signal chain: guitar in, pedals in order, amp out - left to right on a computer, top to bottom on a phone. Drag a pedal by its handle (mouse or finger) or use the arrow buttons to move it, and the order is saved on the set. Suggest order puts pedals in the usual chain order from their names (tuner, wah and filters, compressor, drive and fuzz, EQ, modulation, delay, reverb, looper), and a new set starts that way. The board also totals the pedals' current draw so you can size a power supply. Set names are links wherever they show up: on a gear page, on a song that uses the set, and in My Boards.
• Notifications - Apprise alerts (ntfy, Pushover, Telegram, and 100+ others) when a guitar's strings pass their interval, with quiet hours and overdue repeats.
• Search everything - the search box in the top bar (on every page) matches gear, songs, artists, presets, sets and setlists at once, and every result is a link to its page. The Gear page keeps its own filter for names, makes, models and spec values like a gauge, plus a string-type filter for the Strings section. The API takes the same search as ?q= on each list, and GET /api/search?q= runs the global one.
• Hideable sections - don't have pedals? Don't care about songs or a wish list? Turn the section off in Settings > Features and it leaves the interface. Hidden sections keep their data.
• Install it like an app - add Gearsmith to your phone's home screen (Share > Add to Home Screen on iPhone, Install app on Android) and it opens in its own window without the browser bar, with a proper icon on both. Long-press the icon on Android for shortcuts to Gear, Setlists and the Tuner. There's no offline mode on purpose: your data lives on your server, and caching pages on the phone would risk showing stale gear after an update.
• Multi-user - admin plus member accounts, everyone with their own login. Each signed-in user can change their own password in Settings > Change password. The current password is required; other signed-in devices are signed out after a change. Administrators can still reset another user's password from Settings > Users. Passwords use salted PBKDF2-HMAC-SHA256, not plain text.
• Token API - per-user API tokens and interactive docs at /api/docs, so you can log a restring or read your collection from anywhere: a script, a shortcut, or an AI assistant. The website sign-in also accepts an existing token in the password field with the username left blank, without showing a token option on the page. Admins can turn off token sign-in under Settings > Features without disabling the API.

Run it

You need Docker. Everything below works with plain docker compose; if you use a GUI manager (Dockhand, CasaOS, Portainer, Synology Container Manager), create a stack/project from the same compose file instead - no .env file is required, fill the ${...} values in the manager's environment editor.

services:
  gearsmith:
    image: ghcr.io/dhrandy/gearsmith:latest
    container_name: gearsmith
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    environment:
      # Your timezone, so "due today" and quiet hours match your clock.
      - TZ=${TZ:-UTC}
      # Set to true once Gearsmith is served over HTTPS (reverse proxy).
      - GEARSMITH_COOKIE_SECURE=${GEARSMITH_COOKIE_SECURE:-false}
      # IP of your reverse proxy, so login rate limits see real client addresses.
      - FORWARDED_ALLOW_IPS=${FORWARDED_ALLOW_IPS:-127.0.0.1}
    ports:
      - 8743:8000

Then:

docker compose up -d

Open http://localhost:8743, create the admin account, and delete the example gear once you've clicked around. All data (the SQLite database and photos) lives in the ./data directory you mounted - back that up and you've backed up everything.

Environment variables

Variable	Default	What it does
TZ	UTC	Timezone for "due today" and quiet hours, e.g. America/New_York
GEARSMITH_COOKIE_SECURE	false	Set true when served over HTTPS (see reverse proxy below)
FORWARDED_ALLOW_IPS	127.0.0.1	IPs trusted to set X-Forwarded-For (your reverse proxy), so rate limits see real client addresses
GEARSMITH_DATA_DIR	/app/data	Where the database and photos live inside the container
GEARSMITH_NOTIFY_WORKER	true	Set false to disable the background notification checker

Reverse proxy

Any reverse proxy works (nginx, Caddy, Traefik, Synology's built-in one). Point it at port 8743, then:

1. Set GEARSMITH_COOKIE_SECURE=true so session cookies are HTTPS-only.
2. Set FORWARDED_ALLOW_IPS to your proxy's IP so login rate limiting sees real client IPs.
3. In Settings > Notifications, set the public app address so notification links point at your URL.

Upgrading

Pull the new image and recreate the container; your data volume carries over. When an upgrade has to reshape the database (0.3.1 does, once, to add the strings type; 0.14.0 does, once, to move knob names onto your gear's controls), Gearsmith first writes a full copy of it next to the original, named like gearsmith-backup-before-0.3.1.db. Once you're happy with the new version you can delete that file.

Notifications

Settings > Notifications takes any Apprise URLs, one per line - ntfy://ntfy.sh/your-topic, pover://user@token, tgram://..., and so on. Gearsmith sends when a guitar passes its restring interval, once when it flips overdue and then every N days (your choice) until you log the restring. Send hour and quiet hours are configurable, and there's a test button.

API tokens and AI assistants

Settings > API tokens creates a token that acts as you over the REST API. Interactive docs (with a "try it" button) are at /api/docs; the OpenAPI spec is at /api/v1/openapi.json. Both require a signed-in session or a valid API bearer token.

The sign-in page does not advertise tokens. To use an existing token on the website, leave Username empty and put the token in the masked Password field. It signs in as the token's owner with a 30-day session, but Settings, account/token management, notifications and backups require username/password sign-in. Revoked tokens and deactivated users cannot start new sessions; sessions already signed in stay active until logout or expiry. Turn off Sign in with an API token in Settings > Features to disable token sign-in while keeping the API available. Keep tokens secret, use HTTPS, and do not put them in URLs.

To connect an AI assistant, use this prompt with your own URL. Provide the token separately through a secure credential store, never in a prompt:

You can manage my guitar gear through the Gearsmith API at https://YOUR-URL-HERE.
Authenticate every request using my token from the secure credential store in the header: Authorization: Bearer <GEARSMITH_API_TOKEN>
For website sign-in, leave Username blank and put that token in the masked Password field. Token sign-in is not shown on the page. Never put the token in a URL, source file, prompt, or log.
The interactive docs are at /api/docs and the OpenAPI spec at /api/v1/openapi.json.
Gear: list and add (GET/POST /api/v1/gear, filter the list with ?type=guitar, amp, pedal, pick
or strings, ?lifecycle=owned, want or sold, and ?q= to search names and specs), read one item (GET /api/v1/gear/{id}), update it (PATCH /api/v1/gear/{id}). Every item
has "favorite" (true/false) and "lifecycle" (owned, want or sold); want items can carry
want_price, sold items sold_date and sold_price. Any item can carry purchase_price (what
you paid) and current_value (what it's worth now), both in USD. GET /api/v1/collection returns
the totals: owned value (value, falling back to price paid), paid, change, plus want and sold. Pedals and amps can list their knob names in
specs.controls ([{name, kind, value?}], where value is your everyday setting), and
specs.modeler marks a multi-effects unit. Strings items (type "strings")
use make for the brand and specs gauge, string_type (electric, acoustic, classical or bass),
material, strings_per_set and sets_per_pack. A guitar's strings_id points at the strings it uses. Every item can carry manual_url (a link
to its manual), and strings items can carry sets_on_hand (unopened sets in stock); logging a
restring with strings_id takes one set off that count.
Restrings: log one (POST /api/v1/gear/{id}/restrings with brand, gauge and optional date, or
strings_id to fill brand and gauge from a strings item and switch the guitar to it) and
check what's due (GET /api/v1/due). Maintenance: list and log entries (GET/POST
/api/v1/gear/{id}/maintenance with date, category - setup, tubes, fret work, repair or other -
and note), edit or delete one (PATCH/DELETE /api/v1/maintenance/{entry_id}).
Sets: GET/POST /api/v1/sets. PATCH /api/v1/sets/{id} with item_ids sets the order, which is the
pedalboard's signal chain for pedals.
Photos: attach one (POST /api/v1/gear/{id}/photos, multipart field "photo"), delete one
(DELETE /api/v1/photos/{photo_id}), or make one the cover (POST /api/v1/photos/{photo_id}/cover).
Songs: list, search and add (GET/POST /api/v1/songs, ?q= searches title and artist, ?gear_id=
finds songs using a piece of gear), read, update or delete one (GET/PATCH/DELETE
/api/v1/songs/{id}). A song has title, artist, tuning, capo, key, bpm, guitar_id, amp_id,
notes, a "rig" list (gear_id, engaged on/off/toggle, knobs as [{name, value}] with text
values) and a "patches" list for modelers (gear_id, patch_ref, patch_name, scenes, note).
Edit single entries with /api/v1/songs/{id}/rig/{setting_id} and
/api/v1/songs/{id}/patches/{patch_id}. ?artist= lists one artist's songs.
Photos on preset settings: POST /api/v1/presets/{id}/photos (multipart field "photo"), DELETE /api/v1/preset-photos/{photo_id}. The preset response contains photos and a cover; the Artists list includes the cover. Song rig rows also accept POST /api/v1/songs/{id}/rig/{setting_id}/photos and DELETE /api/v1/rig-photos/{photo_id}. Photo URLs use the signed-in web session, while the token API returns their paths.
Presets: list and add (GET/POST /api/v1/presets), read, update or delete one
(GET/PATCH/DELETE /api/v1/presets/{id}). A preset has name, artist, amp_id, notes, and the
same "rig" and "patches" lists as a song. PATCH /api/v1/presets/{id}/rig/{setting_id}
updates one rig entry without replacing its rows or setting photos. On the preset page,
knob arrows reorder controls and save immediately. Songs point at presets with a "presets" list
([{preset_id, label, note}]); editing a preset changes every song that uses it.
Preset reads also include chain_summary: the chain's gear and effect names in signal order.
POST /api/v1/songs/{id}/save-as-preset (name, use_in_song) turns a song's chain into a preset.
Artists: GET /api/v1/artists returns songs and presets grouped by artist.
Setlists: list and add (GET/POST /api/v1/setlists with name, notes and songs as
[{song_id, note}] in play order), read one with every song's presets and settings
(GET /api/v1/setlists/{id}), reorder or rename (PATCH, sending songs replaces the list),
or delete (DELETE).
Share links: create or replace one (POST /api/v1/gear/{id}/share or /api/v1/sets/{id}/share
with optional expires_in_days and regenerate), read it (GET) or turn it off (DELETE).
When I tell you I restrung a guitar, log it. When I ask what needs new strings, check the
due list. When I tell you how I set my rig for a song, save it on that song. When I
describe a tone I use in several songs, save it as a preset and link those songs to it.
When I plan a practice, build a setlist from my songs.

Treat tokens like passwords - anyone holding one can read and change your gear.

Backups

Settings > Backup downloads everything as JSON (gear, photo references, sets, songs, presets, restrings, maintenance and stock counts). The photo files themselves live in your data volume, so back up ./data for a complete copy.

Development

pip install -r requirements.txt -r requirements-dev.txt
playwright install --with-deps chromium
GEARSMITH_DATA_DIR=/tmp/gearsmith PYTHONPATH=. pytest -q
GEARSMITH_DATA_DIR=/tmp/gearsmith uvicorn app.main:app --port 8000

Tests cover the API and the UI (Playwright) and run in CI before every image publish. The image builds for linux/amd64 and publishes to ghcr.io/dhrandy/gearsmith on every push to main.

License

MIT - see LICENSE.

Token website sessions cannot open Settings, manage accounts or tokens, read notification credentials, or import/export backups. Those actions require username/password sign-in. This update signs existing sessions out once because older sessions did not record how they signed in. Stored app data and API tokens stay unchanged.