Documentation

Getting started

nagi is a desktop app for designing native audio plugins with a node graph, Faust DSP, and a built-in interface designer. Install it, open a new project, and you have a working signal chain in minutes. This page covers installation, activating nagi Pro, updates, everyday use, and how Faust code and the GUI fit together.

The same guide is built into the app — press F1 in nagi to open it at any time.

Requirements

nagi compiles plugins on your own machine. Besides the app itself, three things need to be present:

  • The Faust compiler — turns your DSP into C++.

  • A Rust toolchain (cargo) — builds the plugin binary. nagi installs the stable toolchain through rustup.

  • A C/C++ linker — Visual Studio Build Tools ("Desktop development with C++") on Windows, the Xcode Command Line Tools on macOS, build-essential on Linux.

On Windows and macOS, nagi detects what is missing and offers to install it (several GB in total; allow tens of minutes). Settings → General shows the status of all three at any time, each with its own Install button.

  • Windows 10 / 11 (x64). On ARM64 machines nagi runs emulated and the plugins it builds are x64.

  • macOS — one universal binary for Intel and Apple Silicon.

  • Linux x64 — beta, verified on Ubuntu 24.04.

There is no cross-compilation: plugins are built for the OS nagi is running on.

Installation

Installers are on the download page.

Windows

  1. Download and run nagi_<version>_x64-setup.exe. If SmartScreen warns, choose "More info" → "Run anyway".

  2. The installer asks, in turn, whether to set up Faust, Rust and the C++ Build Tools. Accept, and they are installed in that order the next time nagi starts.

  3. The Build Tools open Microsoft's own installer and ask for administrator rights. It can take more than ten minutes — leave it open.

  4. Once nagi is running, check Settings → General: when Faust, Rust and the C++ linker all read "Found", you are ready to build.

An .msi is also provided for managed corporate installs, but an .msi install does not receive automatic updates. Use the -setup.exe unless you have a reason not to.

macOS

  1. Open nagi_<version>_universal.dmg and drag nagi.app into your Applications folder.

  2. Launch it once. macOS will refuse with a "cannot verify the developer" warning — nagi is not notarised by Apple, and on macOS 15 and later the Control-click → Open workaround no longer exists.

  3. Open System Settings → Privacy & Security, scroll down to the line "nagi was blocked…", and click Open Anyway.

  4. Launch nagi again. From now on it opens normally.

  5. The linker is the Xcode Command Line Tools. If they are missing, nagi will guide you; xcode-select --install in Terminal does the same.

Plugins you build with nagi do not need this procedure. Files generated locally carry no quarantine attribute, so your DAW loads them as usual.

Settings → General → Universal binary should be ON when you build a plugin to distribute (one file that runs on both Intel and Apple Silicon). Turning it OFF while you work halves the build time, but the result only runs on this Mac's architecture.

Linux (beta)

First install the packages a plugin build needs (Debian / Ubuntu shown). The WebView and audio APIs that ship with Windows and macOS are development packages on Linux:

sudo apt install -y build-essential faust libwebkit2gtk-4.1-dev libgtk-3-dev libasound2-dev libjack-jackd2-dev

  1. .deb: install with sudo apt install ./nagi_<version>_amd64.deb. Dependencies are resolved and nagi appears in your application menu.

  2. AppImage: make the file executable (chmod +x nagi_<version>_amd64.AppImage) and run it. No installation — it is a single file.

  3. On first launch nagi shows a toast if Rust is missing; let it install Rust through rustup from the settings screen. Faust is the one thing nagi cannot install on Linux (there is no official Linux installer), which is why it is in the apt line above.

  • Only the AppImage receives automatic updates. With the .deb, install the new .deb over the old one with the same command.

  • If a build package is missing, the build log prints a sudo apt install ... line before compiling starts. Run it as printed.

  • On Fedora the equivalent of build-essential is gcc; on Arch it is base-devel.

Activating nagi Pro

nagi is free to use: building plugins and installing updates need no account. nagi Pro — a one-time, perpetual licence — unlocks the following:

  • Form / License widgets — add a licence form to the plugins you build. A GUI containing these widgets can only be built with Pro.

  • MCP server — let external AI agents such as Claude Code drive nagi.

Steps

  1. Create an account on this website and open the link in the verification email.

  2. Buy nagi Pro. The licence is attached to the account with the email address used at checkout.

  3. Start nagi, open My Page (top right) and sign in with the same email address and password.

  4. Your licence appears under Pro features. Click Activate on this PC.

  5. When the panel reads "Pro is active on this machine", you are done: the Form / License widgets and the MCP server are unlocked.

Seats

  • One licence can be active on up to 3 machines. My Page shows usage as "Seats x / 3".

  • To move to another machine, click Release this seat on the old one first, then activate on the new one.

  • If the old machine is broken or out of reach, release the seat from the account page → My Licenses on this website.

Good to know

  • Activation stores a signed licence token on the machine. From then on Pro works offline — nagi never phones home at launch.

  • Signing out keeps the machine's Pro activation. nagi signs you out after 30 days without launching; that does not affect Pro either.

  • "No seats available" means every seat is in use — release one from another machine or from the account page. "Email not confirmed" means the verification link has not been opened yet; open it, then sign in again.

  • If a licence shows as "Revoked" and you did not expect that, contact us.

Updates

Updates are free and need no account. Downloads come from the official nagi release server and every file is signature-checked before it is installed, so a tampered download is rejected automatically.

  1. nagi checks for a new version at launch (on by default; toggle "Check for updates at startup" under My Page → Updates). If one exists you get a toast. Nothing is installed or restarted without you.

  2. Open My Page → Updates, click "Check for updates", then "Download and install". Progress is shown in the panel.

  3. When the install finishes, save your work and click Restart now. nagi comes back on the new version.

  • On Linux only the AppImage auto-updates. With the .deb, install the new package over the old one: sudo apt install ./nagi_<version>_amd64.deb.

  • A Windows .msi install is not auto-updated either — run the new -setup.exe.

  • Every version, including older ones, is listed on the download page.

Using nagi

The screen

  • Top bar — File and Edit menus, the project name (click to rename), the Effect / Instrument selector, the Ai, ▶ Play and Build buttons, and the theme picker. A "*" after the name means unsaved changes.

  • Activity bar (far left) — switches between Node Editor / Code / GUI Builder, with Build Log and Settings at the bottom.

  • Sidebar — follows the mode: the node palette in Node, the project files in Code.

  • Workspace — the editing canvas for the current mode.

  • Status bar — readiness, sample rate, playback state.

Three modes

  • Node Editor — wire nodes together to build the DSP visually. The graph is converted to Faust code automatically. For people who would rather not write code, or who want to see the whole picture.

  • Code — edit the project's Faust source (main.dsp) directly. For fine control, or for pasting existing code.

  • GUI Builder — lay out knobs, sliders and other widgets and bind them to parameters.

The basic flow is build the DSP → design the GUI → listen and export. You can move between the three freely at any point.

Quick start

  1. New project — File → New Project (Ctrl+N). Leave the type on Effect; Instrument is for plugins that receive MIDI and generate sound.

  2. Build the DSP — in the Node Editor, place Audio In → Filter → Gain → Audio Out from the sidebar and drag from output ports to input ports to connect them.

  3. Listen — press ▶ Play. The in-app Web Audio engine plays the patch immediately; press again to stop.

  4. Design the GUI — open the GUI Builder. Widgets for the DSP's parameters are added automatically; add more from the palette and bind them in the properties panel.

  5. Export — press Build and confirm. When it finishes you have a .vst3 and a .clap.

Projects and samples

  • A project is a single .mplg file (File → Save, Ctrl+S) holding the DSP, the node graph and the GUI layout.

  • File → Open starts in the samples folder (Windows: %LOCALAPPDATA%\com.nagi.builder\samples). SimpleFilter, SimpleSynth, SimpleReverb, SamplePlayer and others are complete, buildable projects — opening one and pressing Play is the fastest way in.

Builds and where they go

  • With no Build output folder set (Settings → General), the .vst3 is installed to ~/Library/Audio/Plug-Ins/VST3 on macOS and ~/.vst3 on Linux, where your DAW already looks. On Windows it goes to the default location shown in the settings screen.

  • If you set a build output folder, everything — .vst3, .clap (and .component on macOS) — is copied there. "Open the output folder after a successful build" is handy here.

  • The first build compiles the plugin's dependencies and takes a few minutes; later builds are much faster. Progress streams into the Build Log.

  • A few Faust standard-library functions are off limits. Functions licensed GPLv3 (co.FFcompressor_N_chan, co.RMS_*, co.limiter_lad_*, ba.tabulateNd, re.vital_rev and a handful more) stop the build before it starts, and the log names a replacement (compression: co.compressor_mono / co.compressor_stereo; reverb: re.zita_rev1_stereo).

AI assistant

The Ai button in the top bar takes a request like "make a simple low-pass filter" and drafts Faust code or a GUI layout. Everything runs locally: nagi connects to an OpenAI-compatible local LLM server such as LM Studio or Ollama (Settings → AI assistant). Generated code lands in Code mode where you can review and edit it.

Faust code and the GUI

In nagi, Faust UI primitives are the plugin's parameters, and GUI Builder widgets bind to those parameters by address. Keep that mapping in mind while writing code and most of the GUI work happens by itself.

What becomes what

  • hslider("Label", init, min, max, step) / vslider(...) / nentry(...) — a continuous input parameter. In the GUI: a Slider, or a Knob when tagged [style:knob].

  • button("Label") — momentary, 1 while held. checkbox("Label") — a 0/1 toggle. Both become a Button.

  • hbargraph("Label", min, max) / vbargraph(...) — an output parameter the DSP writes and the GUI reads. In the GUI: a Meter.

  • hgroup("Name", ...) / vgroup(...) / tgroup(...) — group parameters and add a level to their address.

Address rules

  • A parameter declared outside any group is /main/<Label> (e.g. /main/Cutoff).

  • Inside a group it nests: /main/<Group>/<Label> (e.g. /main/Filter/Cutoff).

  • A path-style label starting with / nests the same way without wrapping anything in a group (e.g. "/Synth/Filter/Cutoff" → /Synth/Filter/Cutoff in nagi). The bundled sample projects are written this way.

  • Spaces and other symbols become _ ("Stack Voices" → Stack_Voices). Keep labels short and unique within a project.

  • Renaming a label changes its address, so widgets bound to it come loose. Re-bind them to the new address in the GUI Builder's properties panel.

Automatic widgets and manual binding

  • Opening the GUI Builder tab, or pressing ▶ Play, adds a widget for every parameter declared in main.dsp. A widget already bound to the same address is never duplicated.

  • To bind by hand, select a widget and pick from Parameter (address) in its properties. The list contains the real addresses the DSP exposes.

  • min / max / step / init are taken from the declaration; adjust label, colour and size in the properties panel.

Label metadata

Append [key:value] tags to a label to steer GUI generation. Several can be combined (e.g. "Cutoff[style:knob][unit:Hz]").

  • [style:knob] — generate a Knob instead of a Slider. Use it for any continuous control you would turn.

  • [unit:Hz] / [unit:dB] / [unit:s] — the unit shown next to the value.

  • [hidden:1] — no widget. For parameters the plugin drives itself (envelope curve samples and the like).

  • [midi:keyon 69] and other [midi:...] tags — MIDI-driven parameters. They are excluded from automatic widget generation (see the Instrument example below).

Example 1: knobs, a slider and a checkbox

A stereo low-pass filter. Cutoff and Resonance come out as Knobs, Gain as a Slider and Bypass as a Button. Put : si.smoo on any control that modulates audio to avoid zipper noise.

import("stdfaust.lib");

// Each UI primitive becomes one plugin parameter — and one widget.
cutoff = hslider("Cutoff[style:knob][unit:Hz]", 1000, 20, 20000, 1) : si.smoo;
res    = hslider("Resonance[style:knob]", 1, 0.5, 20, 0.01) : si.smoo;
gain   = hslider("Gain", 0.8, 0, 1, 0.01) : si.smoo;
bypass = checkbox("Bypass");

lp = fi.resonlp(cutoff, res, 1) : *(gain);

process = _,_ : par(i, 2, ba.bypass1(bypass, lp));

Example 2: groups as panels

hgroup / vgroup nest the address (/main/Filter/Cutoff), which keeps a large parameter list navigable on the GUI side.

import("stdfaust.lib");

// hgroup/vgroup nest the address: /main/Filter/Cutoff, /main/Output/Gain ...
cutoff = hgroup("Filter", hslider("Cutoff[style:knob][unit:Hz]", 1000, 20, 20000, 1)) : si.smoo;
res    = hgroup("Filter", hslider("Resonance[style:knob]", 1, 0.5, 20, 0.01)) : si.smoo;
gain   = vgroup("Output", hslider("Gain[unit:dB]", 0, -60, 12, 0.1)) : ba.db2linear : si.smoo;
mix    = vgroup("Output", hslider("Mix", 1, 0, 1, 0.01)) : si.smoo;

wet = fi.resonlp(cutoff, res, 1);
process = _,_ : par(i, 2, _ <: (_ : *(1 - mix)), (wet : *(mix)) :> _ : *(gain));

Example 3: a meter (DSP → GUI)

hbargraph is an output parameter — the DSP writes it and the GUI Builder turns it into a Meter widget. attach(x, y) is the standard Faust idiom for passing audio x through untouched while forcing y to be computed.

import("stdfaust.lib");

gain = hslider("Gain[style:knob]", 0.8, 0, 1, 0.01) : si.smoo;

// hbargraph is an OUTPUT parameter: the DSP writes it, a Meter widget reads it.
// attach() keeps the audio path intact while forcing the meter to be computed.
meter(x) = attach(x, x : an.amp_follower(0.2) : ba.linear2db
                       : hbargraph("Level[unit:dB]", -60, 0));

process = _,_ : par(i, 2, *(gain) : meter);

Example 4: an Instrument (MIDI synth)

Set the type in the top bar to Instrument and the plugin receives MIDI from the host. The three parameters tagged [midi:keyon ...] — freq, gain, gate — take the note's pitch, velocity and note-on (nagi recognises them by the words freq / gain / gate in the label).

import("stdfaust.lib");

// Instrument: these three receive MIDI. nagi finds them by the [midi:...]
// tag plus the words freq / gain / gate in the label.
freq = hslider("freq[midi:keyon 69]", 440, 20, 20000, 0.01);
gain = hslider("gain[midi:keyon 0]", 0.5, 0, 1, 0.01);
gate = button("gate[midi:keyon 1]");

att = hgroup("Envelope", hslider("Attack[style:knob][unit:s]",  0.01, 0.001, 2, 0.001));
dec = hgroup("Envelope", hslider("Decay[style:knob][unit:s]",   0.15, 0.001, 2, 0.001));
sus = hgroup("Envelope", hslider("Sustain[style:knob]",         0.6,  0,     1, 0.01));
rel = hgroup("Envelope", hslider("Release[style:knob][unit:s]", 0.3,  0.001, 4, 0.001));
cut = hgroup("Filter",   hslider("Cutoff[style:knob][unit:Hz]", 8000, 20, 20000, 1)) : si.smoo;

env   = en.adsr(att, dec, sus, rel, gate);
voice = os.sawtooth(freq) : fi.lowpass(3, cut) : *(env) : *(gain);

process = voice : *(0.5) <: _,_;

Example 5: a parameter with no widget

// Real parameters the plugin drives itself. No widget is generated for them.
lfoPhase = hslider("LFO Phase[hidden:1]", 0, 0, 1, 0.001);

The Connections graph

The Connections panel at the bottom of the GUI Builder wires widgets and parameters to each other without code: one knob driving several parameters (a macro), a widget enabling or disabling another, a value rescaled before it is passed on. It is simply output → input, drawn as a line.

Troubleshooting

  • Play reports an error — a Faust compile error. Check brackets and semicolons, and the channel count of process (a stereo effect is process = _,_ : ...).

  • Build stops immediately — check the Faust / Rust / linker status under Settings → General. On Linux, run the sudo apt install ... line the build log prints.

  • Build succeeds but the Instrument makes no sound / ignores notes — make sure freq / gain / gate carry [midi:...] tags and the project type is Instrument.

  • No linker on Windows — the Build Tools may be installed without the x64-hosted toolset. Run "Install Build Tools" under Settings → General again to add it.

  • nagi will not open on macOS — follow "Installation → macOS" above and click Open Anyway.

  • Cannot activate Pro — "No seats available": release a seat from another machine or the account page. "Email not confirmed": open the verification link, then sign in again.

In-depth references for the node library, the Faust standard library and build-config.json are being written. Ask in the Community board if you get stuck in the meantime. For the Faust language itself, the official Faust documentation is the place to look.