build-desktop-app

星标10

分支6

更新时间2026年6月10日 15:36

Build, test, package, and release Mako Desktop and the Mako Local Agent. Use when changing packages/desktop, packages/local-agent, shipping a new desktop version, or debugging the desktop release pipeline.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

mako-ai

mako-ai/mako

打开 GitHub 仓库查看创作者相关仓库

下载

Build & release Mako Desktop

Components

Piece	Path	Output
Local Agent	`packages/local-agent`	`dist/index.js` (single-file bundle, plain node)
Desktop shell	`packages/desktop`	`release/*` (dmg/exe/AppImage via electron-builder)
Release pipeline	`.github/workflows/release-desktop.yml`	GitHub Release `desktop-vX.Y.Z`
PR smoke build	`.github/workflows/desktop-ci.yml`	build-only
Website links	`website/lib/downloads.ts`, `website/app/download`	evergreen download page

Local development

pnpm agent:dev                                       # agent on 127.0.0.1:41720
MAKO_DESKTOP_URL=http://localhost:5173 pnpm desktop:dev   # shell against dev stack

The shell skips spawning the agent if one is already listening (or set MAKO_AGENT_SPAWN=0).

Verify a change end-to-end

Typecheck both packages: pnpm --filter @mako/local-agent typecheck && pnpm --filter @mako/desktop typecheck
Smoke the agent API: curl http://127.0.0.1:41720/health, then /test-connection and /execute against a local Postgres/Mongo.
Bundle and re-run under plain node (catches esbuild + native-module regressions): pnpm --filter @mako/local-agent build && node packages/local-agent/dist/index.js
Package unpacked and launch: pnpm --filter @mako/desktop pack:dir && packages/desktop/release/linux-unpacked/mako (use ELECTRON_DISABLE_SANDBOX=1 and DISPLAY=:1 in headless VMs). Verify the packaged app spawned the bundled agent: curl http://127.0.0.1:41720/health.

Ship a release

Bump version in packages/desktop/package.json (semver) in the PR.
Merge to master. release-desktop.yml builds macOS arm64+x64, Windows x64, Linux x64 and creates tag + GitHub Release desktop-vX.Y.Z.
No version bump → no release (the workflow checks for an existing release and skips). Re-run manually with workflow_dispatch force to re-upload.
Evergreen links (used by the website) — do not rename artifacts: https://github.com/mako-ai/mako/releases/latest/download/Mako-{mac-arm64.dmg,mac-x64.dmg,win-x64.exe,linux-x86_64.AppImage}

Gotchas

New agent dependencies must be pure-JS or have a JS fallback; add optional native modules to OPTIONAL_STUBS in packages/local-agent/build.mjs.
onlyBuiltDependencies in pnpm-workspace.yaml must include electron or its binary won't download; the server Dockerfile sets ELECTRON_SKIP_BINARY_DOWNLOAD=1 to keep images lean.
macOS/Windows builds are unsigned until signing secrets are configured — see packages/desktop/README.md for the secret names.
electron-builder maps ${arch} to x86_64 for AppImage names.

同仓库更多 Skills

同仓库

apps

mako-ai/mako

Load when building, editing, or debugging Mako React apps — app files, npm dependencies, data bindings, the @mako/app-sdk hooks (useQuery / useDuckDB / useLocation / useSearchParams / navigate), URL state and shareable deep links, materialized Parquet/DuckDB bindings, and the live preview runtime.

2026-08-0110

dbt-git-workflow

mako-ai/mako

Load for dbt branches, commits, pushes, pull requests, merges, repository sync, or branch cleanup.

2026-07-2810

dbt-jobs

mako-ai/mako

Load when creating, editing, scheduling, running, or debugging dbt jobs and production deployments.

2026-07-2810

dbt

mako-ai/mako

Load when building, editing, running, or debugging dbt models, dbt projects, schema.yml tests, sources, seeds, snapshots, incremental models, materializations, or dbt jobs in the Transforms section.

2026-07-2710

flows

mako-ai/mako

Load when creating, editing, configuring, validating, or debugging database sync flows, connector flows, pagination, incremental sync, destination mappings, and flow form fields.

2026-07-2210

add-mcp-preset

mako-ai/mako

Add a new MCP server preset (connector) to Mako's MCP client system — server URL, auth model (OAuth DCR, pre-registered app, or API key), scopes, icon, tests, and docs. Use when connecting a new external MCP server (like Slack or Close CRM) or changing how MCP connections authenticate.

2026-07-1410

Build & release Mako Desktop

Components

Piece

Path

Output

Local Agent

packages/local-agent

dist/index.js (single-file bundle, plain node)

Desktop shell

packages/desktop

release/* (dmg/exe/AppImage via electron-builder)

Release pipeline

.github/workflows/release-desktop.yml

GitHub Release desktop-vX.Y.Z

PR smoke build

.github/workflows/desktop-ci.yml

build-only

Website links

website/lib/downloads.ts, website/app/download

evergreen download page

Local development

pnpm agent:dev # agent on 127.0.0.1:41720 MAKO_DESKTOP_URL=http://localhost:5173 pnpm desktop:dev # shell against dev stack

The shell skips spawning the agent if one is already listening (or set MAKO_AGENT_SPAWN=0).

Verify a change end-to-end

Typecheck both packages: pnpm --filter @mako/local-agent typecheck && pnpm --filter @mako/desktop typecheck

Smoke the agent API: curl http://127.0.0.1:41720/health, then /test-connection and /execute against a local Postgres/Mongo.

Bundle and re-run under plain node (catches esbuild + native-module regressions): pnpm --filter @mako/local-agent build && node packages/local-agent/dist/index.js

Package unpacked and launch: pnpm --filter @mako/desktop pack:dir && packages/desktop/release/linux-unpacked/mako (use ELECTRON_DISABLE_SANDBOX=1 and DISPLAY=:1 in headless VMs). Verify the packaged app spawned the bundled agent: curl http://127.0.0.1:41720/health.

Ship a release

Bump version in packages/desktop/package.json (semver) in the PR.

Merge to master. release-desktop.yml builds macOS arm64+x64, Windows x64, Linux x64 and creates tag + GitHub Release desktop-vX.Y.Z.

No version bump → no release (the workflow checks for an existing release and skips). Re-run manually with workflow_dispatch force to re-upload.

Evergreen links (used by the website) — do not rename artifacts:

https://github.com/mako-ai/mako/releases/latest/download/Mako-{mac-arm64.dmg,mac-x64.dmg,win-x64.exe,linux-x86_64.AppImage}

Gotchas

New agent dependencies must be pure-JS or have a JS fallback; add optional native modules to OPTIONAL_STUBS in packages/local-agent/build.mjs.

onlyBuiltDependencies in pnpm-workspace.yaml must include electron or its binary won't download; the server Dockerfile sets ELECTRON_SKIP_BINARY_DOWNLOAD=1 to keep images lean.

macOS/Windows builds are unsigned until signing secrets are configured — see packages/desktop/README.md for the secret names.

electron-builder maps ${arch} to x86_64 for AppImage names.

name	build-desktop-app
description	Build, test, package, and release Mako Desktop and the Mako Local Agent. Use when changing packages/desktop, packages/local-agent, shipping a new desktop version, or debugging the desktop release pipeline.