Getting started

Requirements

• macOS: Apple Silicon with macOS 27 or later. There is no Intel Mac or Windows build.
• To build: Git, Node.js 26.12.0 or later, pnpm 10.33.2, and the Xcode Command Line Tools for the native Swift helpers. Without Swift, Apple Foundation Models, Computer Use and the Orvlet Engine report unavailable.
• A model: a local runtime, model files for the Engine, or a cloud API key. Model weights are not bundled.

Build & run

Until a public source repository is published, use the checkout your project contact gives you; the commands below are the supported path from that checkout. Installing dependencies needs a network connection; running the app does not.

cd Orvlet
pnpm bootstrap      # install dependencies and build the workspace
pnpm dev:desktop    # start the desktop app

Local preview app (macOS)

To package an ad-hoc signed Orvlet Preview.app for your own Mac:

ORVLET_ENV=production ORVLET_PREVIEW_IDENTITY=1 \
ORVLET_MAC_ADHOC_PREVIEW=1 ORVLET_DESKTOP_DIST_DIR=dist-local-preview \
pnpm bundle:desktop -- mac arm64

The app lands in packages/desktop/dist-local-preview/mac-arm64/. It is not notarized and is meant for local testing only.

Configure a model

With no model configured, the composer shows Set up a model.

A local model. Start a runtime, then open Settings → Local models or Settings → Model settings → Add provider → Detect local runtimes, press Fetch models and add one. No API key is needed.

ollama pull llama3.2
llama-server -m model.gguf --jinja -c 32768
mlx_lm.server --model mlx-community/Qwen3-4B-4bit

The Orvlet Engine. Open Settings → Model library to use a model already on this Mac or download one, then use the built-in Orvlet Engine provider. A cloud model: in Add provider, choose the template, paste your key and fetch models.

Agent tasks need tool calling, natively or through the Text shim. The first tool-capable model you add becomes the default when none is set.

First task

1. Open a project folder. Its identity is the folder itself; remote folders keep their own identity and never merge by path.
2. Ask for a small, checkable change. Review the diff; approve commands as they appear. New tasks start in Ask before changes.
3. Try /review on a branch, or index a folder as a knowledge collection and ask a question about it.

Command-line interface

node scripts/build-desktop-agent-cli.mjs
pnpm orvlet --help
pnpm orvlet --prompt "Summarize this repo"

Headless runs deny anything that would need an approval unless you pass an explicit mode. See the product page for the command overview.

Troubleshooting

The app will not open on macOS

Check macOS 27+ on Apple Silicon first; LaunchServices reports an incompatible OS before startup. Ad-hoc preview builds are not notarized — open them from Finder with Control-click → Open for local testing.

No models appear

Local runtimes are detected only when you open Local models or press Refresh — that is deliberate. Confirm the runtime is listening, then Fetch models. Keyless local endpoints must not require an invented key; leave the key empty.

Saving a key fails

Credential storage fails closed when the macOS Keychain is unavailable rather than storing weakly. Unlock your login Keychain, then retry.

Something wants the network

Nothing should at startup. Settings → Privacy & network lists each configured service and whether it stays on this Mac, your local network or the internet. See security & privacy.