Install

Chrysalis is one download with nothing else to install. It runs a small server on your device and opens in your browser.

Every download is on the releases page. Pick the file for your system:

System	File
Windows 10 and 11	`Chrysalis-<version>-windows-x64.zip`
macOS, Apple silicon (M1 and later)	`Chrysalis-<version>-macos-arm64.tar.gz`
macOS, Intel	`Chrysalis-<version>-macos-x64.tar.gz`
Linux, most PCs	`Chrysalis-<version>-linux-x64.tar.gz`
Linux, ARM (Raspberry Pi 4 and 5, ARM servers)	`Chrysalis-<version>-linux-arm64.tar.gz`
Android 9 or newer, 64-bit	`Chrysalis-<version>-android-arm64.apk`

#Windows

Download the windows-x64.zip file and unzip it somewhere you keep programs, such as your Documents folder.
Open the unzipped folder and double-click chrysalis.exe.
If Windows shows Windows protected your PC, click More info, then Run anyway. The program is not signed with a paid certificate, so Windows warns about it the first time.
A window opens with the server's log and your browser opens Chrysalis. Keep that window open while you use it; closing it stops Chrysalis.

#macOS

Download the file for your Mac. Not sure which? Apple menu, About This Mac: Chip: Apple M… means macos-arm64, Processor: Intel means macos-x64.
Double-click the download to unpack it.
Open Terminal, type cd (with a space), drag the unpacked folder into the Terminal window, and press Return.
macOS blocks programs downloaded from the internet that are not notarized. Clear that once for this folder, then start Chrysalis:
```
xattr -dr com.apple.quarantine .
./chrysalis
```
Your browser opens Chrysalis. Keep the Terminal window open while you use it.

#Linux

tar -xzf Chrysalis-*-linux-x64.tar.gz
cd Chrysalis-*-linux-x64
./chrysalis

Chrysalis opens your browser when there is a desktop, and prints the address otherwise. To run it as a service, see Settings for the config file and the environment variables.

#Android

On your phone, download the .apk file from the releases page.
Open it. Android asks you to allow your browser to install apps; allow it, then tap Install.
Open Chrysalis. It unpacks itself the first time, starts its server on the phone, and opens it in your browser.
Tap Keep running in the background so Android does not pause Chrysalis while you are in the browser.

Uninstalling the Android app deletes everything it stored. Before you uninstall, export a backup of each app you care about.

The launcher app has a Logs button that shows what the server is doing, which is the first place to look if something does not start.

#Docker

The image is ghcr.io/projectchrysalis/chrysalis-engine, for x64 and ARM64. Save this as docker-compose.yml:

services:
  chrysalis:
    image: ghcr.io/projectchrysalis/chrysalis-engine:latest
    container_name: chrysalis
    restart: unless-stopped
    ports:
      - "8788:8788"
    volumes:
      - ./chrysalis-data:/chrysalis

Then start it and read the setup link from its log:

docker compose up -d
docker compose logs chrysalis

Settings and data live in the /chrysalis volume. The container listens on your network by default, so other devices can open http://<this computer>:8788. If you open Chrysalis by a name instead of an IP address (a reverse proxy or a local DNS name), add that name with CHRYSALIS_ALLOWED_HOSTS.

#From source

With Bun installed:

git clone https://github.com/ProjectChrysalis/Chrysalis-Engine
cd Chrysalis-Engine
bun install
(cd client-agent && bun install)
bun run build:client
bun start

#Staging builds

The staging pre-release is rebuilt every time new work lands on the staging branch. It gets features first and can break. On Android it installs as a separate Chrysalis Staging app with its own data, so a stable install on the same phone is untouched. The Docker tag is :staging.

Installed? Continue with First start.