C64 Commander

Control and manage a C64 Ultimate from Android, iOS, or a self-hosted web deployment on your local network.

Features

• Cross-platform: Native Android and iOS apps, plus a Docker-based web interface for macOS, Windows, or Linux.
• Cross-device: Supports Commodore 64 Ultimate (all editions), Ultimate 64, Ultimate 64 Elite, and Ultimate 64 Elite II.
• Dashboard: Machine controls, Quick actions, drive and printer shortcuts, SID mixer, and streams on a single page.
• Playlists: Build playlists from local files, C64U storage, the High Voltage SID Collection (HVSC), or CommoServe search results. Autoplay, shuffle, and subsong selection.
• Disk management: Mount, unmount, and rotate multi-disk groups across drives.
• Configuration: Browse and edit the full C64 Ultimate configuration tree.
• Diagnostics: Inspect activity logs, traces, latency, and connection health across App, REST, FTP, and Telnet activity.
• Device Switcher: Switch between devices and run parallel health checks.

Quick Start

Android

1. Download the latest APK from Releases.
2. Open the APK and allow installs from unknown sources if prompted.
3. Tap Install.

iOS

1. Set up SideStore.
2. Download the latest IPA from Releases.
3. In SideStore > My Apps, tap + and select the IPA.

SideStore refreshes the app signature automatically every 7 days.

Web (Docker)

The web version is self-hosted for LAN use. Requirements: Docker on Windows, macOS, or Linux. A Raspberry Pi Zero 2W or 4B with 512 MiB RAM or more is sufficient.

Install Docker: Docker Desktop (Windows/macOS) or Docker Engine (Linux). The image supports linux/amd64 and linux/arm64.

mkdir -p ./c64commander-config && chmod 0777 ./c64commander-config

docker run -d --name c64commander -p 8064:8064 \
  -v ./c64commander-config:/config --restart unless-stopped \
  ghcr.io/chrisgleissner/c64commander:<version>

Open http://<host-ip>:8064 in a browser.

If a network password is configured in Settings > Device > Network password, the web interface requires login with the same password.

Variant Selection

Variant metadata is authored once in variants/variants.yaml and generated into web, Android, iOS, and workflow inputs by npm run variant:generate.

• Android workflows intentionally support both c64commander and c64u-controller.
• iOS and web workflows build and publish only the default c64commander variant in this repository.
• Set APP_VARIANT=c64u-controller before npm run cap:build or npm run variant:generate when you want to generate the Android controller variant locally.
• Local side-by-side web testing can still build different variants, but it relies on distinct origins such as different localhost ports rather than runtime storage partitioning.

Examples:

APP_VARIANT=c64u-controller npm run cap:build
APP_VARIANT=c64u-controller npm run variant:generate

First Connection

Ensure the C64 Ultimate is on your local network with required services enabled:

On the C64 Ultimate:

1. Press CBM+Restore and open Network services & timezone.
2. Enable:
   • Web Remote Control Service - REST API used for most control and status operations
   • FTP File Service - required for browsing and transferring files for playlists and disk collections
   • Telnet Remote Menu Service - used for a small set of advanced operations not available via REST, such as power cycle
3. Note the IP address from Wired Network Setup or WI-FI Network Setup.

In C64 Commander:

1. Open Settings > Device > Connection.
2. Enter the C64 Ultimate IP address or hostname.
3. A green health indicator at the top right confirms the successful connection:

Pages

Home

Operational dashboard: machine controls, quick actions, light effects, drives, printer, SID mixer, streams, and configuration snapshots.

Play

Build playlists for programs and songs sourced from the local device, C64U storage, HVSC, or CommoServe. Supports autoplay, shuffle, repeat, subsong selection, and automatic song length discovery.

Browse & Import

Choose an import source, browse its contents, then add files to your playlist or disk collection.

Disks

View drive state, mount and eject images, and manage disk collections with multi-disk group rotation.

Configuration

Browse and edit the full C64 Ultimate configuration: categories, items, sliders, toggles, and per-item refresh.

Settings

Connection, appearance, diagnostics, playback defaults, HVSC integration, and device-safety controls.

Docs

Built-in guides for setup, workflows, and day-to-day usage.

Diagnostics

Tap the top-right status badge to open diagnostics.

Provides health checks, activity logs, trace inspection, filter editor, and latency analysis across App, REST, FTP, and Telnet contributors.

Switch Device

Long-press the top-right status badge to open the device switcher.

The switcher shows all configured devices with real-time health status, allowing instant switching and quick identification of connectivity or device issues.

Display Profiles

The layout adapts automatically based on viewport width: Small (phones), Standard (large phones and small tablets), and Large (tablets and desktops). Override in Settings > Display Profile.

Small display	Standard display	Large display

Troubleshooting

Can't reach the device

• Confirm the C64 Ultimate and your device are on the same network.
• Verify the IP address or hostname in Settings > Device > Connection.

Device becomes unresponsive

C64 Commander includes Device Safety controls under Settings > Device Safety to throttle REST and FTP traffic. REST mutations use a single in-flight lane; presets and advanced controls tune FTP concurrency and backoff behavior.

• Presets: Relaxed, Balanced (default), Conservative.
• Advanced controls: FTP concurrency, read coalescing, cooldowns, backoff strategy, circuit-breaker thresholds, discovery probe interval.
• The Relaxed preset can overwhelm some setups. Start with Balanced or Conservative.

iOS specifics

• App expired: SideStore refreshes every 7 days automatically.
• Account/App ID limits: Remove unused sideloaded apps and retry.
• Install/signing errors: Re-download the IPA and verify its checksum.
• Telnet-backed controls: Power Cycle, Clear Flash, and other Telnet-only actions use the native socket bridge on iOS and Android. Support is discovered from the connected device's live Telnet menu graph, so device-specific gaps stay visible as disabled controls with inline explanation instead of disappearing.

Advanced Topics

Network Security

The C64 Ultimate firmware exposes REST over HTTP and files over plain FTP. C64 Commander follows that model and does not add encryption.

• Password authentication is supported.
• Diagnostics and traces redact sensitive values (including network password headers) before export.

Optional hardening:

1. Run C64 Commander Web behind an HTTPS reverse proxy (Caddy, Nginx).
2. Keep C64 Ultimate and client devices on an isolated VLAN or dedicated LAN segment.
3. Do not expose C64 Commander or C64 Ultimate to the public internet.

Web Server

Authentication

• No network password configured: the UI opens directly.
• Network password configured in Settings > Device > Network password: login is required. The server injects the password into proxied C64U requests.
• The password is persisted in /config/web-config.json. Successful login creates an authenticated session cookie (HttpOnly, SameSite=Lax; add Secure only for HTTPS deployments).

Security settings

• Plain-HTTP LAN deployments keep session cookies HTTP-compatible by default so the documented Docker flow can authenticate successfully.
• Set WEB_COOKIE_SECURE=true only when the app is served over HTTPS or an HTTPS reverse proxy. Set WEB_COOKIE_SECURE=false to force HTTP-compatible cookies explicitly.
• FTP host override is disabled by default. Set WEB_ALLOW_REMOTE_FTP_HOSTS=true only in trusted setups.

Logging

Web server logs go to container stdout/stderr and are mirrored in the in-app diagnostics overlay.

Updating

After deploying a new image, open the app once to activate the new service worker. Reload any tabs still holding the old shell.

docker pull ghcr.io/chrisgleissner/c64commander:<version>
docker rm -f c64commander
docker run -d --name c64commander -p 8064:8064 -v ./c64commander-config:/config --restart unless-stopped ghcr.io/chrisgleissner/c64commander:<version>

Rollback: redeploy the older image and reload.

Linux auto-update

An updater script is available at scripts/web-auto-update.sh.

• --track tags (recommended): tracks GitHub release tags.
• --track ref: tracks a branch/ref and rebuilds from source on update.

Important

Use --track tags for normal deployments. Use --track ref only for development.

chmod +x scripts/web-auto-update.sh
mkdir -p ./c64commander-config

Release-tag mode:

./scripts/web-auto-update.sh \
  --track tags \
  --interval 300 \
  --container-name c64commander \
  --config-dir ./c64commander-config

Branch/ref mode:

./scripts/web-auto-update.sh \
  --track ref \
  --ref feat/web \
  --interval 120 \
  --container-name c64commander-dev \
  --config-dir ./c64commander-config-dev

systemd service:

sudo tee /etc/systemd/system/c64commander-updater.service >/dev/null <<'EOF'
[Unit]
Description=C64 Commander Web Auto Updater
After=network-online.target docker.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/c64commander
ExecStart=/opt/c64commander/scripts/web-auto-update.sh --track tags --interval 300 --container-name c64commander --config-dir /opt/c64commander/config
Restart=always
RestartSec=10
User=pi
Group=pi

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now c64commander-updater.service

Optional GitHub API token (avoids rate limits):

export GITHUB_TOKEN=<your-token>

For Developers

• Documentation index
• Developer guide
• Chaos/fuzz testing

HVSC performance

Use npm run test:perf for the fast local smoke suite. It now combines the web scenario lane, the web secondary lane, and a deterministic Node data-path lane that measures HVSC browse/index plus playlist query hot paths.

The perf-nightly workflow uses the same collectors with an explicit profile model:

• smoke for quick manual validation
• nightly for the scheduled CI run
• manual-extended for deeper manual investigations

Perf artifacts are written to ci-artifacts/hvsc-performance/ as both JSON and Markdown summaries.

Third-party notices: npm run notices:generate regenerates THIRD_PARTY_NOTICES.md. npm run build packages notices into distribution bundles automatically.

Acknowledgments

High Voltage SID Collection (HVSC)

The High Voltage SID Collection is an archive of C64 SID music. C64 Commander integrates HVSC for browsing, searching, and playing SID tunes with metadata and song-length support.

The primary HVSC entry point is now the Add items chooser. If the library is not ready yet, the app prepares it there instead of asking you to run separate manual download and ingest steps from the Play page. The Play page keeps only status, reindex, and reset controls for recovery.

Commodore and the C64 Ultimate

Thanks to Commodore for creating the Commodore 64 and to the creators of the C64 Ultimate for extending the platform with modern hardware.

Third-Party Libraries

C64 Commander uses many open-source libraries. Notices are generated via scripts/generate-third-party-notices.mjs and published as THIRD_PARTY_NOTICES.md.

License

GPL v3. See LICENSE.