Chrysalis

The AI frontend you can reshape just by asking.

Chrysalis runs on your own computer or phone and opens in your browser. Pick the
apps you want from the built-in Store, and every one of them is files the
built-in agent can change while you watch. Ask for a feature and it builds it.
Your chats, characters and keys are stored on your device.

Install

Pick the download for your system from the
releases page.
Nothing else needs to be installed.

Want new features before they are stable? The
staging pre-release
is rebuilt from the staging branch on every change. It can break. On Android it
installs as a separate Chrysalis Staging app with its own data, so your stable
app is untouched.

Already have Bun? bun install -g chrysalis-engine, then run chrysalis.

On macOS, start with start.command, not chrysalis. These builds do not carry
a signature macOS accepts, so opening chrysalis directly is blocked or closes
straight away with killed. start.command
clears the download flag, signs the program for that Mac and starts it — use it
again after each update. The Bun install above avoids this.

Bring your own tools

Your whole Chrysalis is a folder of plain files under git. Run chrysalis workspace in a terminal — Chrysalis makes itself a command the first time it
starts, so there is nothing to install (open a new terminal if it was already
running). It prints where the workspace is; point your editor or coding agent
at it and work normally, saves reach open pages on their own. AGENTS.md there
explains the layout to whatever agent reads it. For the parts that are not
files, ./chrysalis api GET /v1/apps calls the running engine's API.

First start

Chrysalis opens your browser (or prints a link) with a one-time setup address.
Open it, create your account, and add a model connection in
Settings > API connections. The first account is the admin: it can add
more people, each with their own workspace, agent and apps.

Lost the link? It is in the window where Chrysalis started and in
data/logs/chrysalis.log. Forgot a password? Stop Chrysalis and run
chrysalis reset-password <name>.

Settings file

Server settings live in config.yaml, created on first start with a note on
every line. chrysalis paths prints where it is:

Put a config.yaml next to the program to keep everything in that folder instead
(a portable copy, for example on a USB drive).

port: 8788
lan: false          # true: phones and other computers on your network can open it
allowedHosts: []    # extra names, like chrysalis.home or a Tailscale name
ssl:
  enabled: false    # HTTPS: phones need it for the microphone and installing as an app

Admins can change the same settings in Settings > Server, which applies them
right away, shows a QR code for your phone, and tells you when a new version is
out. You can also ask the agent ("let my phone connect"); it shows you exactly
what will change and waits for you to approve.

Every setting also works for a single run as an environment variable or a flag:

CHRYSALIS_PORT=9000 chrysalis
chrysalis --lan --port 9000 --no-open-browser
chrysalis --help

Using it from your phone

• Chrysalis on your computer, phone on the same Wi-Fi: turn on
  Allow other devices on my network in Settings > Server and scan the QR code.
• Chrysalis on the phone itself: install the Android app. It runs the server
  on the phone and opens it in your browser. Uninstalling the app deletes its
  data, so export backups from your apps first.
• Away from home: put both devices on Tailscale and
  use the computer's Tailscale address. tailscale cert gives you HTTPS files
  for ssl.certPath and ssl.keyPath.

Updating

Chrysalis keeps your data in its own folder, so an update never touches it.

• Downloads (Windows, macOS, Linux, portable): when a new version is out, an
  Update to X button appears at the bottom of the Where to? page (the
  page every new tab opens on) and in Settings > Server. Click it: Chrysalis
  downloads the update, restarts, and reloads the page.
• Android: install the new APK over the old one.
• Bun: bun add -g chrysalis-engine@latest.
• Docker: docker compose pull && docker compose up -d (the :staging tag for
  staging), or git pull && docker compose up -d --build to build it yourself.
• From source: git pull && bun install && (cd client-agent && bun install) && bun run sandbox:fetch && bun run build:client, then restart.

Apps you have changed are never overwritten: the Where to? page marks apps
with an update, and updating merges it with your edits. To move an app to another device, or keep a copy
before uninstalling, use Export app in its info pane, then Import app >
Backup file on the other side. The backup carries the app's data and keeps
updating from where it came from.

Running from source

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

bun run dev restarts on every change. bun test runs the suite and
bun run typecheck checks every project.

Release builds

bun run dist                      # every platform, from any one machine
bun run dist linux-x64 npm        # some of them
ANDROID_HOME=~/android-sdk bun run dist android-apk   # the APK (JDK 17+)

Output lands in out/dist/. Set CHRYSALIS_ANDROID_KEYSTORE,
CHRYSALIS_ANDROID_KEYSTORE_PASSWORD, CHRYSALIS_ANDROID_KEY_ALIAS and
CHRYSALIS_ANDROID_KEY_PASSWORD to sign the APK for release; keep that keystore,
since Android only updates an app signed with the same key.

Community

Questions, ideas and apps you have built: join the
Project Chrysalis Discord. Bugs go in
GitHub issues.

Branches and contributing

• main is stable. Releases are tagged here.
• staging is where new work lands first. Open pull requests against staging.

Every push and pull request runs the tests and builds every download, then
starts each one on Windows, macOS, Linux and in Docker. To release, merge
staging into main, set the version in package.json, and push a tag:
git tag v1.2.3 && git push origin v1.2.3.

License

Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).
See LICENSE for the full text.

Inspiration

Chrysalis was inspired by pi, the minimal coding agent you
adapt by asking it to build what you need. Chrysalis brings that idea to an AI
frontend, and its agent runs on pi's own libraries.

Built on

Every other dependency is MIT, BSD, ISC, Apache-2.0, or OFL-1.1.