Contents

Installation and development builds

Getting it

It runs on macOS, Linux and Windows (Windows through WSL2). The desktop app is for Apple silicon Macs with macOS 26 or later only; on Linux and Windows, use the Web UI of the tsugumi command.

Preparing the runtime the first time (assembling Tsugumi inside the VM and fetching the Cards’ dependencies) needs an internet connection.

Installing the desktop app (Mac)

Put the latest version from GitHub Releases in /Applications.

Open Tsugumi.dmg and drag it to Applications, or install with this command:

curl -fL -o /tmp/Tsugumi.zip https://github.com/gen740/Tsugumi/releases/latest/download/Tsugumi.zip && ditto -x -k /tmp/Tsugumi.zip /Applications && open /Applications/Tsugumi.app

Releases are signed ad hoc (with the virtualization entitlement needed to run the VM), without a Developer ID signature or Apple’s notarisation. An app taken out of a zip downloaded in a browser is stopped by Gatekeeper, so fetch it with curl as above, or remove the quarantine attribute after taking it out:

xattr -dr com.apple.quarantine /Applications/Tsugumi.app

From “Browse Demos” on the home screen, choose “Open a Copy” on the demo you want to try, and once the first preparation is done, press “Run” at the top of the screen. To use the Agent, set the model provider and API key under “API” in the settings, or choose the ChatGPT plan and sign in with “Continue with ChatGPT”. The basic operations are in the README and Usage; what data is sent to outside models is in Security and isolation.

Automatic updates

Releases check GitHub’s latest release after starting and every six hours. If there is a new version, it is downloaded, its checksum, signature, bundle id and version number are checked, and it replaces the app the next time you quit (the resident execution environment continues independently of the app). To update at once, choose “Restart to Update” on the home screen or “Restart to update to …” in the application menu. Under “General” → “Updates” in the settings you can see the current version, check by hand and turn automatic checks on or off.

  • The folder the app is in (usually /Applications) must be writable. An app opened with the quarantine attribute still on (running from elsewhere through App Translocation) cannot update; move it to /Applications and remove the quarantine attribute.
  • The ad hoc signature changes with each version, so the first time an updated version uses an API key, macOS asks once for access to the keychain (choose “Always Allow” and that version will not ask again).
  • During 0.x, project documents and settings may change without migration (compatibility policy).

Using it in the browser (the tsugumi command)

A command for using Tsugumi in the Web UI in a browser instead of the app. It needs neither root nor administrator rights.

Mac and Linux:

curl -fsSL https://github.com/gen740/Tsugumi/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/gen740/Tsugumi/releases/latest/download/install.ps1 | iex

This installs ~/.local/bin/tsugumi. Run it to start the server and open the browser:

tsugumi

Stop it with Ctrl-C. If the same build is already running, it opens a new page on that host. tsugumi <project folder> opens that project on either a new or an existing host. Starts, including starts from the Claude Code plugin, share one lock per data folder, so concurrent commands use one host. A running host from a different build is refused with a message identifying its PID and URL; stop that host before starting the new build.

When a new version comes out, replace it with this command (if it is already the latest, it says so and does nothing). A running tsugumi opens with the new version after you stop and start it again.

tsugumi update
  • What is installed: only the command (~/.local/bin/tsugumi) and what it runs (~/.local/share/tsugumi/<version>.<generation>/). If ~/.local/bin is not on PATH, it says so; it does not change your shell’s settings. tsugumi update or installing again replaces it with a new version (it does not update itself). To remove it, see Uninstalling.
  • Mac (Apple silicon, macOS 26 or later): fetches tsugumi-macos-arm64.tar.gz, which includes Node.js and the VM’s boot disk. Cards run in the same shared Linux VM as the desktop app, so Nix need not be installed separately. The first start takes a few minutes while Tsugumi is assembled inside the VM. The settings shared with the desktop app, and when the two cannot be used at once, are in Web UI.
  • Linux (x86_64 / aarch64): needs Nix. It fetches the source, tsugumi-linux.tar.gz, and builds it with Nix (the first time takes a few minutes; how it works is in Web UI).
  • Windows: needs WSL2 and Nix installed in its Linux. install.ps1 runs install.sh in the default WSL Linux and creates %USERPROFILE%\.local\bin\tsugumi.cmd (it does not change PATH). tsugumi runs inside WSL just as on Linux, and the page opens in the Windows browser. Keep projects on the WSL file system and pass folders as absolute paths as WSL sees them. It can also be installed from a shell in the WSL Linux with the same curl … | sh as on Linux (no tsugumi.cmd is made, but the page still opens in the Windows browser).
  • Each installation, including the same version again, gets a separate runtime directory. The installer checks the checksum (.sha256), builds or unpacks there, and runs tsugumi --version before atomically switching current. A failed build or version check leaves the current command usable. Old runtimes stay available because a running host can still read their assets; stop hosts and use tsugumi uninstall --yes to remove installer-marked generations. Foreign directories under the install root are preserved. To choose a version, use the environment variable TSUGUMI_VERSION.

Building from source

What follows is how to build the app, and how to develop or change Tsugumi itself and its runtime. Unless stated otherwise, run the commands at the root of the repository.

An app built from source is the development version (Tsugumi Dev). It is a separate app from the release, with its own support folder (~/Library/Application Support/Tsugumi-dev/), so it does not touch the release’s VM and both can run at once. The development version does not update itself (“Development and release versions” in Releasing).

Prerequisites

  • Nix (with flakes enabled)
  • Xcode or the Command Line Tools
  • Only to build the VM’s boot disk (when there is no published one): Apple container (the version is TSUGUMI_CONTAINER_VERSION in macOS/Container/versions.env; after container system start)

Dependency pins are defined in flake.lock, Package.swift and the relevant package lock files.

Minimal steps

macOS/build-app.sh

open -g dist/Tsugumi.app

Each stage in detail

Enter the development shell and build the core (tsugumid) and the SDK:

nix develop

cmake -S . -B build -G Ninja && ninja -C build

The shared VM’s boot disk (a kernel and a small rootfs with Nix, written to dist/tsugumi-vm/). If there is a published one at gen740/tsugumi-vm, it is downloaded; otherwise it is built with Nix inside a container (no separate Linux host or remote builder is needed). It changes only when the pinned nixpkgs or macOS/Container/vm-boot.nix changes; after changing them, publish it with macOS/tools/publish-vm.sh. Tsugumi itself (tsugumid and the rest) is built by Nix inside the VM on its first boot, from the shared source (macOS/Container/vm-system.nix; rebuilt only when the source changes):

macOS/Container/build-image.sh --vm

The builder’s resources can be set with the environment variables TSUGUMI_BUILDER_CPUS (default 8), TSUGUMI_BUILDER_MEMORY (default 16G) and TSUGUMI_BUILDER_VOLUME (the volume for the Nix cache, default tsugumi-builder-nix).

macOS/build-app.sh packages the app into dist/Tsugumi.app. It bundles the shared module host, the demos, the VM’s boot disk and the source the VM assembles Tsugumi from (macOS/Container/vm-source.txt), and signs it. For development signing and release channels, see Releasing. If there is no boot disk, run build-image.sh --vm first. With --release it builds a release (used by the release workflow; Releasing).

Starting the VM needs a code signature with the virtualization entitlement, so during development too, use the dist/Tsugumi.app that macOS/build-app.sh makes (a binary started directly with swift run has no signature and cannot start the VM). tsugumi-vmctl, which test scripts use to operate the VM, is built with macOS/tools/build-vmctl.sh.

The app icon macOS/Resources/AppIcon.icns is generated from docs/assets/tsugumi-icon.svg and committed. After changing the SVG, regenerate it with swift macOS/Resources/tools/make_icon.swift.

Checking after building

tests/ci-local.sh

The test suites and commands are in Repository tests.

Uninstalling

Quit Tsugumi and stop any running tsugumi server first. Preview what the command-line installer will remove, then apply it:

tsugumi uninstall
tsugumi uninstall --yes

This removes all runtime generations carrying the installer’s marker, their Nix result links on Linux, and ~/.local/bin/tsugumi. It preserves projects and their run history, settings, API credentials, the Mac shared VM, Nix, and the Nix store. Unrelated files and unmarked directories under the installation root are preserved; each marked generation is removed entirely. A launcher or installation directory that has been replaced or redirected is refused rather than deleted. This command applies to installations made by install.sh; manage a Nix profile installation with Nix instead.

On Windows, run tsugumi uninstall --yes from Windows through the installed tsugumi.cmd. The command removes the installation in the default WSL distribution and deletes the Windows launcher only after success. Running it directly inside WSL leaves the Windows launcher in place; remove %USERPROFILE%\.local\bin\tsugumi.cmd separately in that case. WSL and its distributions are preserved.

The native Mac app is separate: move Tsugumi.app from Applications to the Trash. Its shared support folder (~/Library/Application Support/Tsugumi) is preserved, so reinstalling can reuse the VM and settings. Do not remove that folder if another Tsugumi installation still uses it.

docs/INSTALL.md (Markdown)