# Installation

> Install @native-sdk/cli, platform package layout, prerequisites, and success signals for a working native binary on each host OS.

- Repository: vercel-labs/native
- GitHub: https://github.com/vercel-labs/native
- Human docs: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/llms-full.txt

## Source Files

- `README.md`
- `packages/native-sdk/README.md`
- `packages/native-sdk/scripts/build-binaries.sh`
- `packages/native-sdk/npm/darwin-arm64/README.md`
- `docs/src/components/home/install-toggle.tsx`

---

---
title: "Installation"
description: "Install @native-sdk/cli, platform package layout, prerequisites, and success signals for a working native binary on each host OS."
---

`@native-sdk/cli` installs the `native` command as a Node dispatcher plus a per-platform prebuilt binary, and ships the SDK source your apps build against in the same package so `native init` and `native dev` work offline after install.

## Prerequisites

| Requirement | Notes |
| --- | --- |
| **Host OS** | macOS 11+, Linux, or Windows (desktop is the mature surface; mobile targets are experimental) |
| **Node.js + npm** | Required for the `native` wrapper (`bin/native.js`); the CLI binary itself is native |
| **Optional deps enabled** | Platform binaries ship as `optionalDependencies` — do not install with `--no-optional` / `--omit=optional` |
| **Zig 0.16.0+** | Not required before install; resolved on first `native dev\|build\|test` (see [Zig toolchain](#zig-toolchain)) |
| **Network (first build)** | macOS/Linux may download the pinned Zig archive from ziglang.org if none is on `PATH` |

Canvas-only apps need no system WebView SDK. System WebView / packaging checks are host-specific and surface under `native doctor`:

| Host | Extra checks when you need WebView or packaging |
| --- | --- |
| **macOS** | WKWebView (in-box); `codesign`, `xcrun notarytool`, `hdiutil` for signing/DMG |
| **Linux** | GTK4 + WebKitGTK 6.0 (`pkg-config --exists gtk4` / `webkitgtk-6.0`) for system WebView |
| **Windows** | WebView2 Evergreen runtime for system WebView |

## Install the CLI

<Tabs>
  <Tab title="Humans">
```bash
npm install -g @native-sdk/cli
```
  </Tab>
  <Tab title="Agents">
```bash
npx skills add vercel-labs/native
```
Installs the discovery skill so agents load version-matched guidance from the installed CLI via `native skills`. You still need `@native-sdk/cli` on the machine for `native` itself.
  </Tab>
</Tabs>

<Note>
Install runs **no package scripts**. The prebuilt `native` binary arrives as a platform optional dependency (`@native-sdk/cli-<platform>` with `preferUnplugged: true`). The main package carries SDK payload (`src/`, `build/`, `build.zig`, `build.zig.zon`, `app.zon`, `skills/`, `skill-data/`).
</Note>

Project-local install also works when you prefer not to global-install:

```bash
npm install @native-sdk/cli
npx native version
```

## How the install resolves a binary

```text
npm install -g @native-sdk/cli
        │
        ├─► @native-sdk/cli
        │     bin/native.js          # Node dispatcher (PATH entry: `native`)
        │     src/, build/, …        # SDK apps build against
        │     optionalDependencies   # all eight platform packages, exact version pin
        │
        └─► package manager installs exactly one matching:
              @native-sdk/cli-darwin-arm64
              @native-sdk/cli-darwin-x64
              @native-sdk/cli-linux-arm64-gnu | -musl
              @native-sdk/cli-linux-x64-gnu  | -musl
              @native-sdk/cli-win32-arm64
              @native-sdk/cli-win32-x64
                    └── bin/native[.exe]
```

`bin/native.js` picks the platform package, `require.resolve`s `bin/native` (or `bin/native.exe` on Windows), ensures execute bits on Unix, then `spawn`s the binary with your args.

| Step | Behavior |
| --- | --- |
| OS/arch map | `darwin` / `linux` / `win32` × `x64` / `arm64` |
| Linux libc | `ldd` / musl loader paths → `gnu` or `musl` package |
| Binary lookup | `require.resolve("@native-sdk/cli-<platform>/bin/native…")`, then legacy `bin/native-sdk-<platform>` for repo-local packs |
| SDK path | Sets `NATIVE_SDK_PATH` to the package root when `src/root.zig` is present (user override always wins) |

All packages share one version (currently **0.4.0**). `optionalDependencies` pins match that version so a given `@native-sdk/cli` always pairs with the binary built from the same release.

## Platform packages

Install `@native-sdk/cli` only. Do not install platform packages directly.

| Package | Target |
| --- | --- |
| `@native-sdk/cli-darwin-arm64` | macOS Apple silicon |
| `@native-sdk/cli-darwin-x64` | macOS Intel |
| `@native-sdk/cli-linux-arm64-gnu` | Linux arm64 (glibc) |
| `@native-sdk/cli-linux-x64-gnu` | Linux x64 (glibc) |
| `@native-sdk/cli-linux-arm64-musl` | Linux arm64 (musl) |
| `@native-sdk/cli-linux-x64-musl` | Linux x64 (musl) |
| `@native-sdk/cli-win32-x64` | Windows x64 |
| `@native-sdk/cli-win32-arm64` | Windows ARM |

Release engineering also stages flat GitHub assets (`native-sdk-<platform>[.exe]` + `CHECKSUMS.txt`) via `packages/native-sdk/scripts/build-binaries.sh` for non-npm distribution. See [Updates and package distribution](/updates-distribution).

## Zig toolchain

`native dev`, `native build`, and `native test` resolve Zig before building. Pin: **`0.16.0`** (`src/tooling/toolchain.zig`).

| Priority | Source |
| --- | --- |
| 1 | `NATIVE_SDK_ZIG` (trusted override) |
| 2 | `zig` on `PATH` when version is compatible (same major.minor, patch ≥ pin; pre-release/dev builds never match) |
| 3 | Managed install at `~/.native/toolchains/zig-0.16.0/zig` |
| 4 | Interactive download from ziglang.org (~55 MB, SHA-256 verified) into (3) |

```bash
# Non-interactive / CI: consent to managed download without a prompt
native dev --yes
native build --yes
native test --yes
```

<Warning>
Managed download covers **macOS and Linux** (aarch64/x86_64) only. On hosts without a pinned archive (including **Windows**), install Zig 0.16.0+ yourself or set `NATIVE_SDK_ZIG` to a compatible binary. Non-TTY sessions without Zig and without `--yes` refuse the download and print the recovery command.
</Warning>

Durable CLI state lives under `~/.native/` (toolchains). Per-app generated build graphs live under `<app>/.native/build/` (gitignored, disposable).

## Environment overrides

<ParamField body="NATIVE_SDK_PATH" type="string">
Absolute or relative path to an SDK/framework root that contains `src/root.zig`. Overrides the package-local SDK (npm wrapper sets this when the package carries source). Use a git checkout when developing against unreleased framework code.
</ParamField>

<ParamField body="NATIVE_SDK_ZIG" type="string">
Path to a Zig executable. Skips PATH and managed-toolchain resolution.
</ParamField>

<ParamField body="NATIVE_SDK_HOME" type="string">
Root for managed toolchains (`$NATIVE_SDK_HOME/toolchains` instead of `~/.native/toolchains`).
</ParamField>

## Verify the install

<Steps>
  <Step title="CLI binary resolves">
```bash
native version
```
Stdout payload (scripts parse this):

```text
native 0.4.0 (commit <hash>, automation protocol v<n>)
```

`version` / `--version` print version, build commit, and automation protocol on **stdout** so binary/framework skew is a one-command check.
  </Step>
  <Step title="Host diagnostics">
```bash
native doctor
```
Default mode is informational (exit 0). Use `--strict` when you want non-zero exit on warnings:

```bash
native doctor --strict
native doctor --manifest app.zon --strict
```
  </Step>
  <Step title="First app build (optional smoke)">
```bash
native init install_smoke
cd install_smoke
native dev --yes
```
Success: a native window opens with the scaffolded counter; subsequent runs are incremental. First compile builds the app against the SDK payload and may install Zig.
  </Step>
</Steps>

### Success signals by host

| Signal | macOS | Linux | Windows |
| --- | --- | --- | --- |
| `native version` prints `native <semver> (commit …)` | required | required | required |
| Platform optional package present | `cli-darwin-*` | `cli-linux-*-gnu` or `*-musl` | `cli-win32-*` |
| Zig for builds | PATH, managed `~/.native/toolchains`, or `NATIVE_SDK_ZIG` | same | PATH or `NATIVE_SDK_ZIG` (no managed download) |
| Pure canvas window (`native dev`) | Metal/AppKit host | software/real window host | Win32 host |
| System WebView doctor check | WKWebView available | WebKitGTK 6.0 + GTK4 | WebView2 registry client present |

## Troubleshooting

| Failure | Cause | Fix |
| --- | --- | --- |
| `No native binary found for <os>-<arch>` / `Expected package: @native-sdk/cli-…` | Optional deps omitted, or unsupported arch | Reinstall with optional deps: `npm install -g @native-sdk/cli` (not `--omit=optional`) |
| `Unsupported platform: <os>-<arch>` | Dispatcher only maps darwin/linux/win32 × x64/arm64 | Use a supported host |
| `Cannot make binary executable` | Permission/bit on Unix binary | `chmod +x` on the path printed by the error |
| Zig missing in non-TTY / CI | Managed download needs consent | Pass `--yes`, or install Zig 0.16.0 and ensure `zig version` is compatible |
| Wrong Zig on PATH | Incompatible major.minor or dev build | Install matching Zig, set `NATIVE_SDK_ZIG`, or let managed install take over on macOS/Linux |
| `cannot locate the Native SDK framework` | No `NATIVE_SDK_PATH` and binary cannot walk to `src/root.zig` | Reinstall `@native-sdk/cli` (must include SDK payload) or set `NATIVE_SDK_PATH` to a full checkout |
| Linux WebView doctor fails | Missing GTK4 / WebKitGTK 6 | Install distro packages (`libgtk-4-dev`, `libwebkitgtk-6.0-dev` or equivalents); not required for canvas-only apps |
| Windows WebView doctor fails | WebView2 runtime missing | Install Evergreen WebView2 Runtime |

## What install does *not* set up

- **CEF / Chromium** — optional; use `native cef install` when an app selects the Chromium web engine (see [Web engines](/web-engines)).
- **Owned `build.zig`** — zero-config apps need none; `native eject` is optional.
- **Agent skill files in the workspace** — `native init` does not copy skills; use `npx skills add` or `native skills get`.
- **Frontend node_modules** — only for `--frontend …` scaffolds; installed on first managed frontend run.

## Next

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Scaffold with `native init`, run `native dev`, and verify the first live window.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full verb list: init, dev, check, test, build, doctor, skills, and failure modes.
  </Card>
  <Card title="Agent skills" href="/agent-skills">
    Discovery install and `native skills list|get` for version-matched agent guidance.
  </Card>
  <Card title="Updates and package distribution" href="/updates-distribution">
    Multi-platform npm layout, version sync, and binary release assets.
  </Card>
  <Card title="Platform support and security" href="/platform-security">
    Host capability matrix across macOS, Linux, Windows, and experimental mobile.
  </Card>
  <Card title="Contributing" href="/contributing">
    Toolkit checkout prerequisites (Zig, Node, pnpm) when working on the repository itself.
  </Card>
</CardGroup>