Documentation

Dune is an AI-first desktop IDE: a native workbench, a Monaco editor, a built-in coding agent, and Open VSX extensions. It ships as Dune.app.

The app itself is proprietary — you download binaries via Homebrew or GitHub releases. You extend it by building and publishing Open VSX–compatible extensions (themes, languages, and more) and by adding agent plugins under .dune/.

Dune ships through one Homebrew tap — duneyou/homebrew-dune. Tap it once, then install any of the three packages it publishes. They all ride the same vX.Y.Z release, so a single brew upgrade moves them together.

brew tap duneyou/dune

What the tap installs

brew install --cask duneyou/dune/dune-ide
#   -> Dune.app

brew install duneyou/dune/dune-ide-cli
#   -> dune

brew install duneyou/dune/dune-server
#   -> dune-server

After the tap is added you can drop the duneyou/dune prefix — brew install --cask dune-ide and brew install dune-server resolve the same way.

The app — dune-ide

Installs Dune.app into /Applications. The cask does not put dune on your PATH — install dune-ide-cli alongside it for the terminal command.

The launcher — dune-ide-cli

A VS Code–style code shim: it locates Dune.app and forwards your arguments. The formula is named dune-ide-cli so it never shadows Homebrew core's OCaml dune — the installed binary is still dune. If you use both, decide which wins on PATH (for example brew unlink dune).

It looks for the app at $DUNE_IDE_BIN first, then inside a sibling Dune.app, then /Applications/Dune.app. Point it at a build elsewhere with:

export DUNE_IDE_BIN="/Applications/Dune.app/Contents/MacOS/Dune"
dune .

The server — dune-server

Serves a folder's files, git, .dune/ config, and an interactive terminal over HTTP + WebSocket, so the desktop app can attach to a workspace on another machine. The interactive /pty endpoint requires the hyper HTTP backend:

brew install duneyou/dune/dune-server
TISH_HTTP_BACKEND=hyper dune-server --workspace "$PWD" --port 8787 --token secret
curl localhost:8787/health   # {"ok":true}

Upgrade and uninstall

brew update && brew upgrade dune-ide-cli dune-server
brew upgrade --cask dune-ide

brew uninstall dune-ide-cli dune-server
brew uninstall --cask dune-ide   # add --zap to remove app support files
brew untap duneyou/dune

Or skip Homebrew entirely: drag Dune.app from a release DMG into /Applications. Releases are published on duneyou/dune.

1. 1

   Open a folder. Welcome screen, or File ▸ Open Folder. Dune treats that folder as the workspace.

2. 2

   Command palette. Cmd+Shift+P (macOS) / Ctrl+Shift+P. Almost every action is listed there — search “theme”, “terminal”, “git”, “extensions”, “remote”.

3. 3

   Sign in to Hypery. Open the account / agent side of the workbench and complete sign-in. Without a Hypery account the editor, git, and extensions still work; the agent does not.

4. 4

   Install a language extension. Open Extensions, search Open VSX (for example a Python or TypeScript pack), and install. Grammar-only and declarative extensions (themes, languages, settings, commands) work immediately.

5. 5

   Talk to the agent. Open chat, pick Agent or Ask, and describe a change. Use @ to attach files or web search. Plan mode writes a checklist you can review before it edits.

6. 6

   Optional CLI. From a terminal, dune . opens the current folder.

The workbench is a set of internal modules — Explorer, Terminal, Git, Agent, Extensions, Remote, and more. You can disable non-core ones like a feature flag; core modules always stay on. Here's the short tour.

VS Code color themes work as-is. Dune adds extra chrome tokens — window frame, floating cards, traffic lights — so a theme can style the whole app, not only the editor. Bundled Dune themes seed into your user extensions on first launch: four Desert times of day (Daybreak, Sunset, Dusk, Midnight) and four Dessert flavors (Macaron, Blackberry, Boysenberry, Blackcurrant).

To write or publish your own theme — including optional dune.* chrome keys — see Theme authoring.

"statusBar.background": "#E0A968",
"statusBar.foreground": "#1A0F05",
"editor.foreground": "#EADCBF"

Dune renders standard VS Code color themes and extends them. Real VS Code ignores unknown keys, so one theme file can serve both editors. Ship themes as normal extensions via Open VSX.

Three tiers of effort

1. Ship unchanged. Your existing VS Code theme works full-app — Dune derives UI colors from standard colors keys.
2. Tune for Dune. Add dune.* keys for floating cards, pill tabs, and macOS traffic lights.
3. Full chrome identity. Frame elbows, segmented rails, canvas wallpaper, and chrome typography restyle the whole workbench shell.

Minimal extension

A theme is a VS Code extension with a contributes.themes entry. Set an explicit id if you expect the label to change later — otherwise the label becomes the settings id and renaming orphans user prefs.

{
  "name": "my-theme",
  "publisher": "me",
  "version": "1.0.0",
  "engines": { "vscode": "^1.70.0" },
  "categories": ["Themes"],
  "contributes": {
    "themes": [
      {
        "id": "me.my-theme",
        "label": "My Theme",
        "uiTheme": "vs-dark",
        "path": "./themes/my-theme.json"
      }
    ]
  }
}

{
  "name": "My Theme",
  "colors": {
    "editor.background": "#1C110C",
    "editor.foreground": "#EADCBF",
    "statusBar.background": "#E0A968",
    "statusBar.foreground": "#1A0F05",
    "dune.app-canvas": "#140C08",
    "dune.part-radius": "12px",
    "dune.part-gap": "8px",
    "dune.part-pad": "8px",
    "dune.tab-radius": "8px",
    "dune.tab-inset": "8px",
    "dune.titleBar.controlsPadX": "12",
    "dune.titleBar.controlsPadY": "10",
    "dune.titleBar.controlsColorClose": "#c4453f",
    "dune.titleBar.controlsColorMinimize": "#e0b23f",
    "dune.titleBar.controlsColorZoom": "#5f9e54"
  },
  "tokenColors": []
}

Install and test

Copy the extension folder to ~/.dune/extensions<publisher>.<name>/ and reload Dune. Or publish to Open VSX and install from the Extensions view. After switching themes, the first paint of the next reload may briefly show the previous colors — a boot cache for flash-free startup; it self-corrects in the same load.

If the theme does not appear, check ~/.dune/last-theme-scan.json for the scan's view of your extension.

What Dune reads

The dune.* namespace

Every dune.* key lives in the ordinary colors map. There are two contracts:

• CSS-value keys (almost all of them). Dotted and hyphenated spellings are equivalent (dune.surface.editor ≡ dune.surface-editor). Values can be colors, lengths, shorthands, calc(), gradients, or SVG data-URIs.
• Native macOS window-control keys — exactly eight under dune.titleBar., read by exact dotted spelling. Hyphenated forms do nothing. Unset = fully native buttons. Harmless on other platforms.

Typos die silently — an unknown dune.* key becomes a CSS variable nothing reads. Prefer the key list below, or copy keys from a bundled Desert / Dessert theme after install.

Recipes

Each recipe is additive and safe to ship to VS Code too.

Floating-card layout

"dune.app-canvas": "#1C110C",
"dune.part-radius": "12px",
"dune.part-border-width": "1px",
"dune.part-gap": "8px",
"dune.part-pad": "8px",
"dune.split-size": "8px"

Pill tabs

"dune.tab-radius": "8px",
"dune.tab-inset": "8px",
"dune.tab-gap": "3px",
"dune.tab-divider-width": "0px",
"dune.tab-row-h": "46px"

Tinted traffic lights (macOS)

"dune.titleBar.controlsPadX": "12",
"dune.titleBar.controlsPadY": "10",
"dune.titleBar.controlsColorClose": "#c4453f",
"dune.titleBar.controlsColorMinimize": "#e0b23f",
"dune.titleBar.controlsColorZoom": "#5f9e54",
"dune.titleBar.controlsDiameter": "13"

Collections

Group themes into named sections of the picker with duneThemeCollections. Entries must match theme labels exactly. Ignored by VS Code.

"contributes": {
  "themes": [ /* … */ ],
  "duneThemeCollections": [
    {
      "id": "me.warm",
      "label": "Warm",
      "order": 1,
      "blurb": "Desert hues",
      "themes": ["My Theme", "My Theme Dusk"]
    }
  ]
}

Packaging traps

• Set an explicit theme id if labels may change.
• Bump extension version on every release — seeded / bundled installs re-copy only when the version changes.
• Publish to Open VSX as a normal VS Code theme extension.

Troubleshooting

• dune.* key does nothing — typo, wrong spelling on a native titleBar key, or an illegal value on a non-dune. standard key.
• Not in the picker — check ~/.dune/last-theme-scan.json: bad JSON, missing contributes.themes, or folder not under ~/.dune/extensions.
• First paint shows old colors — expected; the boot cache self-heals in the same load.
• Editor right, terminal wrong — set terminal.* keys; the 16 ANSI slots are yours to define.

Highest-value dune.* keys for most themes. Dotted and hyphenated forms are equivalent except for the eight macOS dune.titleBar.* controls, which require exact dotted spelling.

Dune has three extension layers, and they compose — a VS Code theme, an MCP server, and a project skill can all be active in the same workspace.

Built-in features

The workbench itself is a set of internal modules (Explorer, Terminal, Git, Agent, Extensions, Remote, and others). You can disable non-core ones like a feature flag — they stay installed, they just do not activate. Core modules always stay on.

VS Code extensions

Install from Open VSX in the Extensions view, or drop a VSIX into ~/.dune/extensions. Dune also scans ~/.vscode/extensions and ~/.cursor/extensions, so packs you already have are picked up.

What works today:

• Declarative package.json contributions: languages, TextMate grammars, themes, commands, keybindings, settings.
• Extensions with a main entry run in a Node or Bun extension host. Set dune.ide.extensionHost.runtime to auto (default), node, or bun. Native .node addons need Node.

The vscode API surface is still growing toward VS Code 1.96-line parity. Grammars, themes, and many commands are solid; arbitrary marketplace extensions that depend on the full Electron host are not a guarantee yet. Building and publishing your own extensions for Open VSX is supported.

Agent plugins

These live next to your code under .dune/ (project) and ~/.dune/ (user). Project wins on name conflict.

The agent is also an MCP client: configure stdio servers in .dune/mcp.json (or user MCP settings) and their tools show up in chat.

Dune reads VS Code JSON where it already exists, and prefers .dune/ when both are present.

User settings live in Dune's user directory (same idea as VS Code's User settings.json).

The desktop launcher and the headless binaries share one agent loop. Put dune on your PATH and open any folder from the terminal.

dune .                                   # open the current folder
dune -g src/main.rs:42:5                   # jump to line 42, column 5
dune --wait CHANGELOG.md                  # block until closed (good for $EDITOR)

TISH_HTTP_BACKEND=hyper dune-server \
  --workspace ./workspace --port 8787       # headless workspace

dune and dune-server are the two binaries the Homebrew tap ships — see Homebrew packages. dune-headless, dune-cloud-agent, and dune-cloud-run are not distributed through the tap; they ship inside Dune.app and on cloud workers.