The Nautili desktop app: install, connect, run governed sessions
Install the Nautili desktop app on macOS, Windows or Linux, sign in to your team, pick a model from the team catalog and run a governed coding session.
15 min readLast reviewed October 19, 2026Verified against the stable release manifest for desktop 0.0.4 (published 2026-10-19) and nt 0.0.4
At the end of this guide you will have the Nautili desktop app installed, signed in to your team, and one coding session completed against a model from your team's catalog. You will also know where that session shows up in the dashboard and how the app shares its backend with the nt terminal client.
The desktop app is the first-party client for the Nautili gateway. Every model call it makes goes through your team's gateway with the same identity the dashboard knows about, so spend attribution, guardrail verdicts and routing profiles apply to desktop sessions without any extra configuration. The app does not store provider API keys: the only models it offers are the ones your team's gateway exposes.
Before you begin
- A DevZero account that belongs to at least one team. Sign-in happens in your browser.
- A team with a gateway in the
readystate. Without one the app signs you in but shows Inference is unavailable for this team. See the quickstart. - macOS on Apple silicon, Windows x64, or Linux x64. There is no Intel Mac build and no ARM Linux desktop build in this release.
- A local git repository to work in. The Review tab needs git to show a diff.
- Optional: the
ntterminal client (curl -fsSL https://nautili.ai/install.sh | bash). The app andntshare one background service on this machine, so a login in either covers both.
Step 1: Download and verify the installer
Open nautili.ai/download. The page reads the stable channel manifest at https://releases.nautili.ai/stable/latest.json and highlights the row for your operating system.

| Row on the download page | File in the 0.0.4 manifest |
|---|---|
macOS (Apple Silicon), .dmg | nautili-desktop-mac-arm64.dmg |
Windows (x64), .exe installer | nautili-desktop-win-x64.exe |
Linux AppImage (x64), .AppImage | nautili-desktop-linux-x86_64.AppImage |
| Linux .deb (x64), Debian, Ubuntu | nautili-desktop-linux-amd64.deb |
| Linux .rpm (x64), Fedora, RHEL | nautili-desktop-linux-x86_64.rpm |
Each Download button goes through https://www.nautili.ai/download/stable/<platform-key> (for example darwin-arm64-dmg) and lands on the versioned file under https://releases.nautili.ai/stable/desktop/<version>/.
Every release publishes a SHA256SUMS file next to its assets, linked from the bottom of the download page as Checksums: desktop. Compare the hash before you open the installer.
On Windows, run certutil -hashfile nautili-desktop-win-x64.exe SHA256 in PowerShell and compare the output with the sha256 field for windows-x64-nsis in latest.json. The manifest is plain JSON with version, publishedAt, cli, desktop and sums keys, and each desktop entry carries url, sha256 and size, so it is also the file to read from a script.
Step 2: Install for your operating system
Nautili is not yet signed with a trusted certificate, so each operating system asks you to confirm once. The macOS and Windows steps match the notice on the download page and the install docs.
macOS. Open the .dmg, drag Nautili to Applications, then clear the quarantine flag once:
Without this step, Gatekeeper reports the app as damaged on first open. The command removes the quarantine attribute from the bundle and its contents.
Windows. Run nautili-desktop-win-x64.exe. It is a one-click per-user installer with no prompts. On the SmartScreen dialog choose More info, then Run anyway.
Linux. For the AppImage, mark it executable and run it:
For Debian and Ubuntu, sudo apt install ./nautili-desktop-linux-amd64.deb. For Fedora and RHEL, sudo dnf install ./nautili-desktop-linux-x86_64.rpm. The packaged binary and the .desktop launcher are named io.devzero.nautir, so io.devzero.nautir on the command line starts the installed app.
Step 3: Sign in and pick a team
Start the app. On first launch it starts the Nautili background service, the same server process the nt terminal client uses (nt serve --service), on a loopback port with a private password, then shows the login gate. If nt already started the service, the app adopts it. Because the app and nt share that service, a login in either one covers both.

Click Log in with DevZero. The app opens your browser at the control plane (api.nautili.ai for a production build) and runs an OAuth 2.1 authorization-code flow with PKCE under the public client id nautili. The gate changes to Pick your team in the browser. If no browser window appears, use Open browser again or Copy link and paste the URL into a browser on the same machine.
Sign in with your DevZero account, then choose a team on the consent page. The browser returns to a local callback, the backend the app points at stores the grant, and the session view opens. Access tokens are 15-minute JWTs that the app refreshes in the background, so you only see the gate again when a refresh fails for good.
To confirm which account and team you are on, open Settings (the first tab is Preferences; the others are Appearance, Notifications, Shortcuts, DevZero, Projects, Worktrees, Providers, Models, Extensions, Experimental, About and Servers) and select the DevZero tab. It shows Signed in as, Team, Gateway and Inference gateway, plus Switch team and Log out. The command palette has the same actions as Switch DevZero team, Choose DevZero gateway and Log out of DevZero.
Out of the box the app talks to the local background service. The Servers tab in Settings lists every server the app knows about; the Options section below uses it to add a server running on another machine.
Step 4: Pick a model from your team's catalog
The model picker shows what your team's routing profile and catalog expose, and nothing else. The only provider is DevZero, and the models under it are the ones your team admin connected in the dashboard: provider accounts under Routing (Catalog, Providers), with their credentials under Connections, Provider keys. The app itself does not store provider keys.
Open the picker from the Choose model control in the prompt bar or the command palette. The dialog title is Select model, with a Search models field. Model ids are the same author/slug strings the gateway accepts on the wire, for example anthropic/claude-haiku-4.5, so what you choose here is what shows in the trace.
Two states are worth knowing:
- Loading models... appears for a moment after sign-in while the catalog is fetched from the backend. The catalog is re-resolved every ten minutes.
- No models are available for your team yet. means the catalog came back empty. Ask the team admin to connect a provider and model in the dashboard, then restart the app; the catalog is also re-resolved every ten minutes.
The picker hides older models by default. A Manage models (N hidden) link at the bottom tells you how many, and opens the list where you can toggle them back on. If a model offers more than one thinking effort, Cycle thinking effort in the command palette switches between levels.
Step 5: Run a session and review the diff
Open a repository with Open project from the command palette. New session starts a fresh session in it.
Type a task in the prompt bar. The placeholder reads Ask anything… "…", with a rotating example in the quotes. A concrete request that names a file works best:
Press Send. The agent reads the file, proposes an edit, and may ask to run a command. When a tool needs approval you see Allow once, Allow always and Deny. How much the agent may do without asking is set per session in the prompt bar under Choose mode: Manual (ask before commands and file changes), Accept edits (the default: change files freely, ask before commands), Plan (read and plan, change nothing) or Full access (run commands and change files without asking). Pick Manual for your first run so you see every change and command before it happens.
Switch to the Review tab to see the diff. Each file expands to a unified diff. Without a git repository the tab says No tracked changes and offers Create Git repository.
To run the test yourself, open the integrated terminal with Toggle terminal and run your project's test command. The prompt bar's Shell mode runs a single command through the session instead, so its output stays in the transcript.
Verify: where the session shows up
Every call the desktop app makes carries identity the dashboard can group on. The app sets these on each request to the gateway:
| Header | Value |
|---|---|
Authorization | the bearer token from your sign-in; the gateway reads user and team from it |
X-Dz-Workload-Type | nautili |
User-Agent | nautili/prod/<version>/<artifact>, for example nautili/prod/0.0.4/desktop |
X-Dz-Session-Id | the desktop session id |
X-Dz-Labels | agent=<agent name> |
traceparent | a W3C trace id derived from the root session, so a resumed session rejoins its trace and a sub-agent shares its parent's |
The app does not send X-Dz-User or X-Dz-Team. The token already carries both, verified, and the gateway drops any client-supplied copies. It does not send X-Dz-Project either: the gateway would record it as a department, which the app does not know, and the People page resolves it from the user's team instead.
Open the dashboard and check three screens:
- Sessions: your desktop session appears as one session, keyed by the
X-Dz-Session-Idabove. A sub-agent spawned inside the session gets its own session id but shares the parent's trace. - Traces: look for requests with workload type
nautili. Each request shows the model, the serving paths the router tried and which one served, and a content-filter notice when a guardrail blocked, redacted or flagged it. - People: spend by user. The desktop session is attributed to the account shown under Signed in as in the app, under the team you picked at sign-in.
The DevZero settings tab shows which gateway the app is using and its state: ready, not installed, not connected yet, offline or state unknown. Only ready serves traffic; in any other state the models stay visible but disabled.
Options
Share sessions with nt, or add a server on another machine
Locally there is nothing to do: the app and nt use the same background service, so they already see the same projects and sessions, and a login or logout in one applies to both.
For a server on another machine, start it there with the terminal client:
Confirm it is up from the machine running the app:
In the app, open Settings, select Servers, and click Add server. Fill Server address with http://<host>:4096 and Password with the value you chose; the username is always opencode. The dialog shows Checking… and then adds the row; Could not connect to server means the server did not answer or rejected the password. The sign-in lives on each server, so a server you add needs its own Log in with DevZero the first time you use it.
Permissions
Choose mode in the prompt bar sets how much the agent may do without asking, per session: Manual asks before commands and file changes; Accept edits (the default) changes files freely and asks before commands; Plan reads and plans but changes nothing; Full access runs commands and changes files without asking. Whatever the mode, a prompt that does appear offers Allow once, Allow always and Deny.
Managed configuration
An admin can push settings a developer cannot override. The app's server reads opencode.json, opencode.jsonc, nautili.json or nautili.jsonc from /etc/opencode on Linux, /Library/Application Support/opencode on macOS and %ProgramData%\opencode on Windows, and on macOS also an MDM payload under the ai.opencode.managed domain. Managed documents rank after user documents, so a managed model or experimental.policies entry wins.
Coming from the terminal?
The desktop app and nt share one background service. If you know the terminal client, this is where each command moved.
nt command | Desktop equivalent |
|---|---|
nt login | Log in with DevZero on the first-launch gate |
nt logout | Settings, DevZero tab, Log out |
nt whoami | Settings, DevZero tab: Signed in as, Team, Gateway |
nt models | Choose model in the prompt bar or command palette |
nt (TUI) | the main session window |
nt run "<message>" | no equivalent; the app has no headless mode |
nt serve --port 4096 | not needed for local use: the app and nt share the background service. Add a remote server under Settings, Servers |
nt upgrade | none; download the new version from nautili.ai/download |
DEVZERO_TOKEN headless auth | not supported in the app; sign in through the browser |
| preprod | not a flag: preprod is a separate Nautili Preprod build (nt-preprod on the terminal side) compiled against api.nautili.dev |
What the desktop app adds: the Review tab with per-file diffs, an integrated terminal, several projects and worktrees in one window, and the Servers switcher.
Troubleshooting
| Symptom | What it means | Fix |
|---|---|---|
| SymptommacOS says the app "is damaged and can't be opened" | What it meansThe quarantine flag is set on an unsigned bundle | FixMove the app to Applications, run xattr -dr com.apple.quarantine "/Applications/Nautili.app", open again |
| SymptomWindows SmartScreen blocks the installer | What it meansUnsigned publisher | FixClick More info, then Run anyway |
| SymptomLinux: the AppImage opens as a text file or "Permission denied" | What it meansThe file is not executable | Fixchmod +x nautili-desktop-linux-x86_64.AppImage, then run it |
| SymptomDevZero could not complete this login. with The browser never came back with an authorization. | What it meansThe browser flow did not reach the consent page, or the attempt timed out | FixClick Try again, finish the DevZero sign-in and pick a team on the consent page; check the browser did not block the local callback |
| SymptomThe gate keeps reappearing after a successful login | What it meansThe sign-in lives on the server the app is using, and that server changed | FixCheck which server is selected under Settings, Servers; log in on the server the app actually uses |
| SymptomYour DevZero sign-in has ended strip over the session | What it meansA token refresh failed and could not be retried | FixClick Log in again; your open session stays |
| SymptomCould not connect to server. Is there a server running at `<url>`? | What it meansThe server the app points at did not answer; your sign-in is not the problem | FixFor a remote server, start it with nt serve; for the local service, run nt service status or restart the app |
| SymptomNo models are available for your team yet. | What it meansThe catalog is empty for this team | FixAsk a team admin to connect a provider and model under Routing in the dashboard, then restart the app or wait for the next catalog refresh |
| SymptomInference is unavailable for this team | What it meansThe team's gateway is not ready | FixOpen DevZero in settings and check the gateway state; an admin installs or reconnects the gateway from the dashboard. The gateway screen's Check again re-reads it |
SymptomCould not connect to server when adding http://<host>:4096 | What it meansnt serve is not running on that port, or the password is wrong | Fixcurl -u opencode:<password> http://<host>:4096/api/info; the username is always opencode and the password is the NT_PASSWORD value the server was started with |
Next steps
- The Nautili terminal client if you prefer
ntin a terminal, or want to runnt serveon another machine as described above. - Nautili gateway quickstart to stand up the gateway and connect the first provider and model.
- Govern LLM traffic with guardrails to put budgets and content rules in front of desktop sessions.
- Install Nautili for the terminal client, if you want
nt runfor scripted sessions alongside the app. - Gateway quickstart to connect a provider and model so the picker has something to show.
- Guardrails overview to set budgets and content rules that apply to desktop sessions in
enforcemode. - Spend attribution to see how the
nautiliworkload type and session ids roll up in People and Spend.