Installing This Thing Properly
Most people download the installer and double-click it, then complain when it fails three minutes later. The process isn't complicated, but there are a few places where it quietly breaks if you don't pay attention. I'll walk through it in the order it actually makes sense, not the order the README lists. The official download lives on their main site. Don't grab it from third-party mirrors or forums. I've seen modified installers floating around that bundle unwanted components, and the error messages they cause look identical to legitimate installation failures. That's how you waste forty-five minutes debugging something that was never broken in the first place. The latest version at the time of writing is v3.2.1. If the page shows anything newer, stick with 3.2.1 until they patch the network handshake bug that trips up certain ISP configurations. I ran into this on a connection through a carrier in the Kanto region — the installer would sit at "Verifying license" for twelve minutes, then silently fail with a timeout error that points at the wrong thing. The workaround is to run the installer with the --legacy-net flag appended. It's documented in the release notes but buried on page four, which is why nobody uses it.
What You Need Before You Start
Windows 10 build 19042 or later. macOS 12 or later. The software doesn't officially support anything older, and the compatibility layer it falls back to on older OS versions introduces a performance hit that makes the whole thing feel sluggish. Not worth the hassle. You also need at least 4 GB of free disk space, though 8 GB gives you breathing room for the temp files the installer creates during the component extraction phase. The default install path is C:\Program Files\ToTokyo on Windows and /Applications/ToToky on macOS. Changing it mid-installation doesn't work — the registry entries and launch configuration hardcode the path, and fixing it afterward requires editing JSON files by hand. Just pick the default and move on. Make sure you're logged in as an administrator on Windows, or your user account has full read/write access on macOS. The installer will warn you if it doesn't have permissions, but sometimes the warning gets swallowed by UAC prompts and you end up with a half-installed mess that won't run at all.
The Actual Installation
Download the correct package for your OS — they split the builds, and running the Windows installer on macOS won't crash, it'll just do nothing and leave you confused. Double-click the .exe or .dmg. On macOS, you may need to right-click and select Open the first time because of the gatekeeper signature, even though the app is signed. I've had users insist the installer is corrupted when it's literally just Gatekeeper being Gatekeeper. The setup wizard will ask for your license key. This is the part where most people hit a wall. The key is a 24-character string, and it's case-sensitive. Entering it with a capital "O" instead of a zero, or vice versa, produces a silent failure — no error message, the app just won't launch afterward. Keep the key open in another window or write it down. Don't trust your memory. After you enter the key, the installer checks it against their server. This step requires an active internet connection. If your connection drops even for a second, the check fails and you have to restart the installer. There's no resume function. I once spent twenty minutes re-downloading the package because my Wi-Fi flickered during a coffee break, only to realize the download itself was fine and I just needed to re-run the installer with the same key.
Get the Full Details
Once the key validates, you pick your component selection. The default installation includes everything — the core runtime, the CLI tools, the GUI wrapper, and the documentation bundle. If you're short on disk space or only need the command-line interface, you can uncheck the GUI wrapper. It saves about 600 MB. The tradeoff is you lose the visual config editor, which means any non-trivial setup requires editing the config file directly. I usually recommend keeping the GUI wrapper unless you have a specific reason not to. The editor saves time even if you prefer working from the terminal. Click Install and wait. The whole process takes roughly eight to fifteen minutes on a modern machine. Older hardware or a slow SATA drive can push it toward twenty. You'll see a progress bar, but don't be alarmed if it stalls at 73% for a minute. That's the component compilation step. It looks frozen but it's working.
Post-Installation Configuration
After the installer finishes, launch the application from your Applications folder or Start menu. The first run will ask you to configure your workspace settings — timezone, data directory, and network proxy if you're behind one. The default settings work for most people. The one setting I always change is the log level. Set it to INFO instead of DEBUG. DEBUG logging fills up your disk fast and slows the application down noticeably. I learned that after watching a machine fill a 256 GB drive in two weeks because someone left it on DEBUG during a long-running job. If you're using a proxy, configure it here. The application doesn't respect system proxy settings, which is a design choice I disagree with but it's consistent across versions. You have to enter the proxy details manually in the app's network configuration panel.
Common Issues and What Actually Fixes Them
The application crashes on startup after installation. This is almost always a leftover conflict from a previous version. Uninstall completely, delete the residual files in %APPDATA%\ToTokyo and %LOCALAPPDATA%\ToTokyo on Windows, or ~/Library/Application Support/ToToky on macOS, then reinstall. I've seen support tickets where people reinstall five times without clearing the old config, which just overwrites corrupted files with more corrupted files. The license validates but the app says "Not Activated." This happens when the machine fingerprint changes — usually because of a hardware replacement or a major OS update. Contact support with your license key and a screenshot of the system info panel. They'll generate a new activation. It takes about an hour, sometimes longer on weekends. CLI commands return "command not found" after installation. Add the install directory to your PATH manually. The installer doesn't always add it, especially on macOS where Homebrew-managed shells sometimes shadow the system PATH during login. Run echo $PATH and verify the ToTokyo bin directory is in there. If it's not, add it to your shell config file.
Downsides Worth Knowing About
The software doesn't support headless operation well. If you're trying to run it on a server without a display, the GUI-dependent components will fail. There's a headless mode, but it requires manual configuration of every setting that the GUI normally handles, and the documentation for it is sparse. If you need server-side automation, look into their API layer instead — it's more stable and better documented than the headless CLI path. The update mechanism is automatic but infrequent. Major releases come out every six to eight months, and patches are sporadic. If you're depending on a specific feature that hasn't shipped yet, don't hold your breath. The development cycle is deliberate, not lazy, but it means you plan around the release schedule rather than getting constant improvements. Resource usage is higher than comparable tools. The GUI wrapper runs a Electron-based process alongside the native runtime, which means you're carrying that overhead whether you use the GUI or not. If you only need the CLI, there's a lightweight package you can install separately that skips the GUI entirely and cuts memory usage by roughly 40%. It's not the default option, so you have to seek it out on their download page under "Alternative Packages."
The To Tokyo Installation Guide Course is functional and reliable once it's running, but the installation process demands more attention than most modern software. Read the release notes before you start. Clear leftover files between versions. Verify your PATH. These small steps prevent most of the problems people encounter, and they save a lot of frustration that could otherwise go into troubleshooting something that was never broken.
