Skip to content

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 ready state. 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 nt terminal client (curl -fsSL https://nautili.ai/install.sh | bash). The app and nt share 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.

The Nautili download page with the Desktop section listing five platform rows and the unsigned-build notice

Row on the download pageFile in the 0.0.4 manifest
macOS (Apple Silicon), .dmgnautili-desktop-mac-arm64.dmg
Windows (x64), .exe installernautili-desktop-win-x64.exe
Linux AppImage (x64), .AppImagenautili-desktop-linux-x86_64.AppImage
Linux .deb (x64), Debian, Ubuntunautili-desktop-linux-amd64.deb
Linux .rpm (x64), Fedora, RHELnautili-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.

# macOS
curl -fsSLO https://releases.nautili.ai/stable/desktop/0.0.4/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing
# Linux
sha256sum -c SHA256SUMS --ignore-missing
nautili-desktop-mac-arm64.dmg: OK

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:

xattr -dr com.apple.quarantine "/Applications/Nautili.app"

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:

chmod +x nautili-desktop-linux-x86_64.AppImage
./nautili-desktop-linux-x86_64.AppImage

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.

The first-launch screen titled Log in to DevZero with the Log in with DevZero button

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:

Add a unit test for parseManifest in lib/releases.ts that covers a manifest with a missing sums field.

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:

HeaderValue
Authorizationthe bearer token from your sign-in; the gateway reads user and team from it
X-Dz-Workload-Typenautili
User-Agentnautili/prod/<version>/<artifact>, for example nautili/prod/0.0.4/desktop
X-Dz-Session-Idthe desktop session id
X-Dz-Labelsagent=<agent name>
traceparenta 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:

  1. Sessions: your desktop session appears as one session, keyed by the X-Dz-Session-Id above. A sub-agent spawned inside the session gets its own session id but shares the parent's trace.
  2. 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.
  3. 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:

NT_PASSWORD=<YOUR_PASSWORD> nt serve --port 4096 --hostname 0.0.0.0

Confirm it is up from the machine running the app:

curl -u opencode:<YOUR_PASSWORD> http://<host>:4096/api/info

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 commandDesktop equivalent
nt loginLog in with DevZero on the first-launch gate
nt logoutSettings, DevZero tab, Log out
nt whoamiSettings, DevZero tab: Signed in as, Team, Gateway
nt modelsChoose 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 4096not needed for local use: the app and nt share the background service. Add a remote server under Settings, Servers
nt upgradenone; download the new version from nautili.ai/download
DEVZERO_TOKEN headless authnot supported in the app; sign in through the browser
preprodnot 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

SymptommacOS says the app "is damaged and can't be opened"What it meansThe quarantine flag is set on an unsigned bundleFixMove the app to Applications, run xattr -dr com.apple.quarantine "/Applications/Nautili.app", open again
SymptomWindows SmartScreen blocks the installerWhat it meansUnsigned publisherFixClick More info, then Run anyway
SymptomLinux: the AppImage opens as a text file or "Permission denied"What it meansThe file is not executableFixchmod +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 outFixClick 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 loginWhat it meansThe sign-in lives on the server the app is using, and that server changedFixCheck 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 sessionWhat it meansA token refresh failed and could not be retriedFixClick 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 problemFixFor 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 teamFixAsk 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 teamWhat it meansThe team's gateway is not readyFixOpen 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>:4096What it meansnt serve is not running on that port, or the password is wrongFixcurl -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

Ready to keep going?

Explore the next guide or start routing through Nautili.