https://github.com/chrisgleissner/c64commander
Cross-platform app (Android/iOS/web) for managing and controlling a Commodore 64 Ultimate over your local network.
https://github.com/chrisgleissner/c64commander
android c64 c64u commodore commodore-64 rest-api retro retrocomputing retrogaming ultimate64
Last synced: 20 days ago
JSON representation
Cross-platform app (Android/iOS/web) for managing and controlling a Commodore 64 Ultimate over your local network.
- Host: GitHub
- URL: https://github.com/chrisgleissner/c64commander
- Owner: chrisgleissner
- License: gpl-3.0
- Created: 2026-01-18T14:42:41.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-18T17:57:20.000Z (25 days ago)
- Last Synced: 2026-05-18T18:35:38.015Z (25 days ago)
- Topics: android, c64, c64u, commodore, commodore-64, rest-api, retro, retrocomputing, retrogaming, ultimate64
- Language: TypeScript
- Homepage:
- Size: 572 MB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
# C64 Commander
[](https://github.com/chrisgleissner/c64commander/actions/workflows/android.yaml)
[](https://codecov.io/gh/chrisgleissner/c64commander)
[](https://www.gnu.org/licenses/gpl-3.0.en.html)
[](https://github.com/chrisgleissner/c64commander/releases)
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](https://github.com/chrisgleissner/c64commander/releases).
2. Open the APK and allow installs from unknown sources if prompted.
3. Tap **Install**.
### iOS
1. Set up [SideStore](https://docs.sidestore.io/).
2. Download the latest IPA from [Releases](https://github.com/chrisgleissner/c64commander/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](https://docs.docker.com/desktop/) (Windows/macOS) or [Docker Engine](https://docs.docker.com/engine/install/) (Linux). The image supports `linux/amd64` and `linux/arm64`.
```bash
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:
```
Open `http://: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:
```bash
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.
- **On Android**, the IP address is recommended. Bare hostnames such as
`u64` or `c64u` rely on mDNS, which is not always reliable on home
networks. The app will attempt mDNS resolution before falling back to
system DNS, and surface a clear "Cannot resolve …" error if both
fail.
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.
## For Developers
- [Documentation index](docs/index.md)
- [DeepWiki architecture and design guide](https://deepwiki.com/chrisgleissner/c64commander)
- [Developer guide](docs/developer.md)
- [Chaos/fuzz testing](docs/testing/chaos-fuzz.md)
## Advanced Topics
Network security, web server configuration, authentication, and Linux auto-update are covered in [docs/advanced.md](docs/advanced.md).
## Acknowledgments
### High Voltage SID Collection (HVSC)
The [High Voltage SID Collection](https://hvsc.c64.org) is an archive of C64 SID music. C64 Commander integrates HVSC for browsing, searching, and playing SID tunes with metadata and song-length support.
### Commodore and the C64 Ultimate
Thanks to [Commodore](https://commodore.net) 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](THIRD_PARTY_NOTICES.md).
## License
GPL v3. See [LICENSE](LICENSE).