A local home for every app.

Latte runs PostgreSQL, DNS, and HTTPS on your Mac, and Frappé builds, serves, and checks each application at its own named origin.

Learning it for the first time? Your first application installs the release and sets up local HTTPS in order. This page lists every command, file and setting of the local environment.

Limits at a glance

Latte runs three services, not your application

Latte is a per-user service supervisor for macOS. It runs one shared PostgreSQL 18 cluster on a private Unix socket, CoreDNS, and a Caddy HTTPS proxy, and keeps a registry of your sites. Applications run under frappe dev in your terminal, not under Latte. Latte also runs a trace collector; the Crema reference describes it.

frappe services          # postgres, dns and proxy with their states
frappe services start    # starts Latte when needed, then its services
frappe services stop     # stops the services; Latte keeps running
latte stop               # stops Latte; the services keep running
latte service install    # start Latte at every login
latte service uninstall
latte version

Expect: frappe services, start and stop print one line each for postgres, dns and proxy with its state, then collector running (127.0.0.1:4318); start starts Latte first when needed, and after stop the services read stopped while Latte keeps running. latte stop prints Latte stopped; its services were left as they were (frappe services stop stops them)., or Latte is not running. latte service install prints Latte now starts when you log in (~/Library/LaunchAgents/dev.caramel.latte.plist), and is running. latte service uninstall prints Latte no longer starts at login; the Latte it started has stopped. and that the services keep running. latte version prints Latte 0.16.0 (control API 1, 2).

The login item is opt-in. latte service install writes ~/Library/LaunchAgents/dev.caramel.latte.plist, takes over from a running daemon, and starts Latte now.

Latte’s logs live in ~/Library/Application Support/Caramel/logs/: latte.log for the daemon, and postgres.log, dns.log, and proxy.log for the services.

The menu bar app shows the services and sites, opens a site, its folder, or its logs, and starts or stops the services. Build it from a Caramel checkout with scripts/build-latte-menu, which writes bin/Latte.app.

Setup runs once per machine

Caramel 0.16.0 runs on Apple Silicon with Apple’s Command Line Tools, and installs from source. From a checkout of the release, these steps install the pinned toolchain, put frappe and latte in ~/.local/bin, and connect .caramel names to Latte. Add ~/.local/bin to your shell’s PATH before the fourth step: from there on the commands run the installed launchers. Each step is safe to run again; prepare refuses an existing bundle folder, so the rm -rf clears it first.

scripts/install-toolchain
scripts/build-release
bin/frappe installations register
frappe services start
rm -rf /private/tmp/caramel-integration-bundle && scripts/install-local-integration prepare /private/tmp/caramel-integration-bundle && sudo scripts/install-local-integration apply /private/tmp/caramel-integration-bundle
latte trust install

Expect: install-toolchain installs the pinned Crystal and PostgreSQL tools into a private 0700 root and writes its path to .caramel-toolchain. build-release installs the locked dependencies and builds bin/frappe, bin/latte and the linter. installations register prints Registered Caramel 0.16.0: PATH and writes the launchers to ~/.local/bin. frappe services start prints the three services and the collector with their states. prepare prints a JSON review with bundle, installs, runs_as and sha256; apply asks for your password and prints Installed Caramel resolver and unprivileged standard-port relay. latte trust install prints Latte certificate trust installed.

Every site gets its own origin

A site’s origin is https://NAME.caramel.

frappe sites
frappe sites remove demo
frappe open

Expect: frappe sites prints one line per site: its name, state, origin and folder. frappe sites remove demo prints Removed demo (https://demo.caramel) from Latte., that its folder, databases, credentials, logs and backups were kept, and the frappe setup command that registers it again. frappe open opens the origin in your browser.

Source changes rebuild the application

frappe dev builds the application, serves it at its origin, and opens the browser when the first build is ready. It watches src, config, db, app, public, shard.yml, shard.lock, and .env with kqueue. Ctrl-C stops the project.

frappe dev
frappe dev --no-open
frappe dev --branch experiment

Expect: frappe dev builds the application, serves it at its origin and opens the browser when the first build is ready; --no-open leaves the browser alone. The terminal prints Type check passed in N ms or Type check failed in N ms when the compiler finishes its semantic stages, then Building NAME…. --branch experiment runs against the database branch that frappe db branch create experiment made.

frappe logs
frappe logs compiler --follow

Expect: frappe logs prints the last 200 lines of the application log through tail; compiler --follow keeps printing. A missing log exits 1.

frappe logs access prints the proxy’s access log. These logs live in ~/Library/Application Support/Caramel/logs/sites/.

Every site gets two databases

Latte gives each site a development database and a separate spec database, each with a runtime URL and a migration URL. Setup writes them to .env with APP_ORIGIN and a fresh APP_SECRET.

Specs never touch development data. frappe corretto migrates the spec database, has Latte clone one for each worker, and gives each worker the values in .env.test. The keys that file cannot set are in the Corretto reference →

frappe seed
frappe db dump
frappe db restore backup.dump
frappe db branch create experiment

Expect: seed runs App.seed against the development database. db dump saves a backup under ~/Library/Application Support/Caramel/backups/SITE_ID/. db restore saves the current database as a pre-restore backup, then restores the file. db branch create clones the development database into branch experiment and prints its connection URL.

A branch is a copy-on-write clone of the development database.

Projects run the release their lock pins

An application’s shard.lock pins its Caramel release, and Frappé hands each project command to that release’s Frappé.

frappe installations
frappe installations install 0.16.0
frappe installations register
frappe installations remove 0.16.0

Expect: frappe installations prints one line per release, its version then its root, with (this installation) after the one you called; with none it says so and names the two ways to install one. install clones the release’s tag into ~/Library/Application Support/Caramel/releases/VERSION, reuses your toolchain when the release pins the same one, builds it and registers it. register prints Registered Caramel 0.16.0: PATH and needs a built bin/frappe and bin/latte; without them it exits 1 naming the build script. remove forgets a release.

Each installation pins two language servers

Each installation pins two language servers that use its private toolchain and the Crystal compiler the release pins, never a global or Homebrew Crystal: crystalline 0.20.0 for definitions, hover, limited completion, diagnostics on save, formatting, document symbols, and signature help, and ameba-ls 0.2.0 for lint diagnostics with Fix and Ignore actions. liger is disabled. The Current release page states the Crystal pin.

frappe lsp install

Expect: The first run needs network access, git and Apple’s Command Line Tools, and prints Building crystalline 0.20.0 with Crystal VERSION (this can take up to 20 minutes)… while it builds crystalline from source. Later runs verify the installed tools.

Older projects copy .zed/settings.json from templates/application in Caramel’s source. frappe installations register puts frappe in ~/.local/bin, where Zed’s login-shell PATH finds it. A one-off PATH=… zed . starts the servers until Zed refreshes the worktree environment, which drops that PATH. CARAMEL_TOOLCHAIN_ROOT is optional, because the installation’s .caramel-toolchain names the toolchain. Before it starts a server, frappe lsp checks the release pinned in shard.lock, as frappe dev does.

Several installations can sit side by side. Each pins its own tools, and installations that share a toolchain root keep their versions apart; different Crystal pins need separate toolchain roots. A project is served by the installation whose frappe Zed finds, and frappe lsp runs under the release the project pins in shard.lock. crystalline navigates into the project’s Caramel dependency in lib/caramel.

To verify, run tail -f ~/Library/Logs/Zed/Zed.log, which shows the lsp crystalline server starting, or run dev: open language server logs in Zed to see the server’s frappe lsp: startup line with its binary, toolchain root and where the root came from.

Editor messages point to their fix

Removing editor tools changes nothing else

The root is the first line of the checkout’s .caramel-toolchain.

frappe doctor