AfterTouch Bose SoundTouch Toolkit

Admin & Setup console: migration, settings, accounts, and diagnostics.

Welcome to AfterTouch

This toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026. It emulates the necessary cloud services locally on your network.

Migration Process at a Glance

🔌 Speaker shell access
The wizard talks to the speaker over one of two transports. The Migration tab probes both automatically and uses whichever your device exposes — you don't have to choose manually.
  • SSH (richest option — required for the XML migration, the /etc/resolv.conf DNS hook, and installing the local CA). Enable it by creating an empty remote_services file on a USB stick, inserting it into the speaker's SERVICE port, and rebooting. Verify on the Migration tab — SSH in the state card's Transports row should show ✅ Reachable. Manual check: ssh -oHostKeyAlgorithms=+ssh-rsa root@<SPEAKER-IP> (no password).
  • Telnet (Port 17000) — the SSH-less fallback. Most SoundTouch firmware exposes a diagnostic shell on TCP/17000 automatically, no USB-stick setup required. Limited to HTTP migrations (no CA install possible without SSH). The state card surfaces this in the same Transports row.
  1. Settings: Review the Settings tab. Ensure the "Target Domain" and "Proxy Domain" use an IP address or domain name that is accessible from your speakers (usually the IP of this server on your local network). You can also edit the Target URL directly from the Migration tab with a Save as default button.
  2. Discovery: Go to the Devices tab to find your speakers on the network. Ensure your speakers are powered on and connected to the same network.
  3. Data Sync: In the Data Sync tab, fetch your current presets, recents, and sources. This step is critical to ensure your local service has all your personalized data before you disconnect from the Bose cloud.
  4. Migration: In the Migration tab the wizard offers a one-click Apply Suggested Plan that picks the right recipe for your speaker (XML over SSH when SSH is available, telnet URL flip otherwise). For mix-and-match across the three independent axes — URL flip transport, DNS interception, CA install — expand Customize this migration. A visible pre-flight check runs before any backend operation touches the speaker.
  5. Verification: After migration and reboot, your speaker will communicate with this toolkit instead of Bose servers.
⚠️ Safety First: Before starting any migration, please read our Professional Migration & Safety Guide. The toolkit automatically creates backups, but understanding the process is key to a smooth transition.

Useful Links

System Settings

Service URLs

Note: These URLs must be accessible from your SoundTouch devices. Use the IP address of this server on your local network (e.g., http://192.0.2.100:8000) rather than localhost.

(Standard services URL)
— ⓘ

AfterTouch's HTTPS endpoint is only needed for certain features — the DNS-based redirect, music-service (Spotify/Amazon) login, and certificate trust. When you use them, its URL is derived from the Target Domain above by default (same host, on the HTTPS port), so you normally don't set anything here. If you don't need plain HTTP at all, you can set the Target Domain itself to an https:// URL and it's used as the HTTPS endpoint as-is. Otherwise, set an override only when a reverse proxy serves HTTPS on a different host or port. Leave it empty to derive automatically. Takes effect after saving.

Landing page (/):
What a browser sees at the root URL. The Player and Admin pages stay reachable at /app and /admin either way.
TLS extra hosts: ⓘ
When you need this: rarely. The TLS certificate already covers AfterTouch's configured server URL, HTTPS URL, and the host's own name. Add entries here only when a speaker can't reach AfterTouch over TLS — typical symptoms include presets resetting on reboot, the BoseApp showing the speaker as offline, or CURLE_SSL_CACERT (60) in the speaker syslog.
How to tell: open the Health tab and look for speaker_marge_url warnings. Each warning names the host a speaker is pointing at; clicking the Add <host> to TLS hosts QuickFix fills this list for you. If that check is clean, this list can stay empty.
Manual path: add one host per line and save. The TLS certificate is regenerated at startup from the merged list of --server-url host, --https-server-url host, the system hostname, any --tls-extra-host / TLS_EXTRA_HOST CLI/env values, and the hosts persisted here. CLI/env wins over persisted on overlap.
Applying changes requires a service restart.
Usually empty. Add a host here only if the Health tab flags a speaker_marge_url warning — or use the one-click QuickFix on that warning to fill it for you.
Device Discovery:
DNS Discovery:
ⓘ
Optional: comma-separated list of DNS servers (e.g., 1.1.1.1, 8.8.8.8).
If empty, AfterTouch defaults to the system nameservers (e.g. from /etc/resolv.conf).
(e.g., :53 or 0.0.0.0:53. Port 53 is required for actual migration)
Integrations:
Spotify …
Checking configuration...
Amazon Music …
Checking configuration...
Google Cloud TTS …
Text-to-speech for speaker announcements. The translate provider needs no credentials; google-cloud needs an API key. Either way, an app key is required to play on the speaker (see the Speaker endpoint docs).
Checking configuration...
Logging:

Requests matching these patterns will be excluded from recording. Use one pattern per line.
Root CA Certificate:
Import this certificate into your OS or browser trust store to trust HTTPS connections to this AfterTouch server from other clients (e.g. curl, Python scripts, browsers).

Known Devices

Spotify: Not Linked
Loading devices...

Initial Data Sync

Before migrating, fetch your presets, recents, and configured sources from the device to ensure they are available locally.

Device Migration

Recorded Interactions & Device Events

Analysis of traffic handled by this service (self), proxied to Bose (upstream), and internal device events (telemetry).

Total Requests: 0

Keeps only the 10 most recent sessions

By Service

    Sessions

      Browse Recordings

      # Time Method Path Status Category Event Details Action
      No interactions found.

      DNS Discoveries

      Hosts discovered via the AfterTouch DNS server. "Self" means the domain was intercepted and redirected to this service.

      Hostname Last Seen Queries Bose? Category Last Client IP
      No DNS discoveries found.

      Local Account Details

      Account Overview

      Loading...

      Spotify Integration

      Register a new Spotify source for this local account. This mimics the official SoundTouch app flow:

      1. Exchange OAuth code for a Bose-mediated token.
      2. Register the source in the local Marge cloud profile.

      Amazon Music Integration

      Register a new Amazon Music source for this local account. This mimics the official SoundTouch app flow:

      1. Exchange OAuth code for an Amazon LWA token.
      2. Register the source in the local Marge cloud profile.

      Connected Devices

      Select an account to view devices.

      Service Health Checks

      Runs a set of checks against the local datastore and flags findings that may need attention. Quick fixes are offered for issues the service knows how to remediate.

      Share a diagnostic snapshot with the project maintainer.
      What does the diagnostic report contain?
      • Health check results and current device state
      • Device XML files from the datastore (no passwords)
      • HTTP response samples from speaker endpoints
      • System files: CA bundle, DNS resolver config
      • Speaker CA bundle and kernel log (via SSH, if reachable)
      • Service log tail
      • Settings file with secrets redacted

      The archive is encrypted with the project maintainer's public key — only they can open it.

      Loading…

      Service Logs

      Live mirror of the service's stderr log. Stderr still receives every line — this is a read-only view for convenience.

      Idle.