# AfterTouch (SoundTouch Toolkit)

# AfterTouch

Bose SoundTouch Toolkit

## 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

🔌 Prerequisite: Enable SSH
Migration requires SSH access. To enable it:

1. Create an empty file named `remote_services` on a USB stick.
2. Insert it into the speaker's SERVICE port and reboot the speaker.

Verify connection:

- Use the Migration tab to select your device and verify that SSH Connection shows ✅ Success.
- Or manually: `ssh -oHostKeyAlgorithms=+ssh-rsa root@<SPEAKER-IP>` (no password).

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).
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, redirect your speaker to this local service. We recommend the XML Configuration method as it is surgical and easily reversible.
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

- Cloud Shutdown Survival Guide
- CLI Reference

## System Settings

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.168.1.100:8000`) rather than `localhost`.

Target Domain: (Standard services URL)
Device Discovery:
Enable Automated Discovery
Discovery Interval:
DNS Discovery:
Enable DNS Discovery Server
Upstream DNS: ⓘ
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`).
DNS Bind Address: (e.g., :53 or 0.0.0.0:53. Port 53 is required for actual migration)
Endpoint Mirroring:
Enable Background Mirroring to Bose Cloud
Prefer Upstream Response for Mirrored Endpoints Mirror Endpoints (one per line, supports * wildcards):
Skip Mirror Endpoints (local only, one per line):
Note: Mirroring sends matching requests (including full headers) to the official Bose servers for parity comparison. If Redact Sensitive Data is enabled in Proxy Settings, credentials will be masked in logs and recordings, but full headers are always sent to Bose to ensure service compatibility.
Spotify Integration:
Client ID:
Client Secret:
Redirect URI:
Checking configuration...
Amazon Music Integration:
Client ID:
Client Secret:
Redirect URI:
Checking configuration...
Proxy Logging:
Redact Sensitive Headers Log Bodies Record Interactions(View in 5. Interactions tab)
Internal Paths (skip recording for these patterns):
Requests matching these patterns will be excluded from recording. Use one pattern per line.

## Known Devices 🔍 Scanning...

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:

### Sync Results

## Device Migration

Device:

### Command Output

### Migration Summary for

Migration Status:

SSH Connection:

Backup: ✅ Found .original config at `/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml.original`

Backup: ❌ Not found

Remote Services Enabled:

AfterTouch Local Root CA Trusted:

HTTPS Connection Test:
Verify the device can reach the server over HTTPS.
URL: ``
Preliminary /etc/hosts Test:
Verify the device's /etc/hosts mechanism before full migration.
Domain: `custom-test-api.bose.fake`
Preliminary DNS Test:
Verify the device can resolve domains via the AfterTouch DNS server.
Domain: `aftertouch.test`
Migration Method:
Current /etc/resolv.conf

Original Config (Backup)

#### Service Implementations

Service | Original URL | Implementation
--- | --- | ---
Marge (Streaming) | loading... |
Stats | loading... |
Software Update | loading... |
BMX (Registry) | loading... |

Current Config (on Speaker)

Planned Config (AfterTouch)

⚠️ Hostname resolution warning:
The planned IP shown above may be incorrect. Migration methods that write IPs to the device (hosts, resolv.conf) will refuse to proceed until the hostname can be resolved from the device itself. Learn more →
Planned /etc/hosts Entries

Note: This method also injects the AfterTouch Local Root CA into `/etc/pki/tls/certs/ca-bundle.crt` to enable secure HTTPS communication.
Planned /etc/resolv.conf Hook

Note: This method injects a persistent DNS priority hook into the DHCP logic (`/etc/udhcpc.d/50default`). It preserves your router's search domain and secondary DNS servers. It also injects the Local Root CA.

## 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

Session:
Category:
Since (YYYY-MM-DD HH:mm:ss):

# | 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.

### Recording Viewer:

### App & Device Events

Time | Type | Data
--- | --- | ---
Select a device to view events.

## Parity Analysis

Detection of discrepancies between AfterTouch local responses and official Bose Cloud responses for mirrored endpoints.

### Parity Mismatches

Time | Method | Path | Reasons | Action
--- | --- | --- | --- | ---
Loading mismatches...

### Mismatch Detail:

Detection Reasons:

⚠️ Large Payload: Rich diff highlighting is disabled to prevent a browser freeze. Showing raw comparison instead.
Local Response (AfterTouch)

Upstream Response (Bose)

## Local Account Details

Account:

### 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.