On This Page

🚧 The Passport Prime SDK is in public beta. Got an idea, or want a dev unit to play with? We'd love to hear from you — hello@foundation.xyz .

The foundation CLI is the single entrypoint for developing Prime apps. It scaffolds new projects, builds for the device, runs the hosted simulator, signs your app, and sideloads it to hardware.

Prerequisites

  • Nix — the SDK is Nix-first. Install from nixos.org with flakes enabled.
  • Git — used by foundation new for initial scaffolding.
  • A Unix-like shell (macOS, Linux). Windows via WSL2 should work but is not yet a tested target.

You don't need to install Rust, the ARM cross-compiler, or cosign2 yourself — the SDK's Nix shell provides all of them.

Install the SDK

Run the release installer. It detects your OS and CPU, downloads the matching archive, verifies its GPG signature and checksum, and installs to ~/.foundation/sdk/.

# Installer URL is shared with early-access partners today.
# After public release, the one-liner will look like this:
curl -sSf https://foundation.xyz/sdk/install.sh | bash

After install:

  • The packaged SDK lives at ~/.foundation/sdk/foundation-sdk-<version>-<target>/
  • ~/.foundation/sdk/current always points to the active version
  • ~/.foundation/sdk/bin/foundation is the stable launcher — the installer adds this to your PATH

Verify with:

foundation doctor

foundation doctor checks for nix, an active Nix shell, SDK root discovery, cargo, the armv7a-unknown-xous-elf target, arm-none-eabi-strip, cosign2, the Slint viewer, and git. It prints pass/fail plus a suggested fix for each.

Five-minute quickstart

foundation develop              # enter the SDK Nix shell
foundation new my-first-app     # scaffold from the default template
cd my-first-app
foundation sim                  # build for hosted execution and launch the simulator

foundation develop drops you into a shell with the right Rust nightly, the ARM target, cosign2, and all dependencies already on PATH. Everything after develop should be run from inside that shell.

foundation new walks you through a few prompts (friendly name, publisher, contact email, icon, app ID, version) and emits a working project. Leave the app ID prompt blank to get a random 128-bit hex ID.

foundation sim compiles your app, stages the binary and manifest into the bundled simulator, and opens the simulator window. Your app appears in the on-device launcher.

What the scaffold gives you

my-first-app/
├── app-config.toml              # app identity, publisher, permissions, signing
├── Cargo.toml                   # Rust dependencies
├── build.rs                     # Slint code generation
├── src/
│   └── main.rs                  # app entry point
├── ui/
│   └── app.slint                # top-level Slint component
├── resources/
│   └── icon.svg                 # launcher icon
└── i18n/
    └── en.json                  # English strings

Two templates ship with the SDK today:

  • default-app — single-page starter (used if you don't pass --template)
  • multi-page-app — router-based multi-screen starter

A minimal app-config.toml

This is what foundation new produces — the single file that defines your app's identity and what it's allowed to do on the device.

app-name = "my-first-app"
friendly-app-name = "My First App"
launcher-app-name = "My First App"
description = "Hello, Prime"
icon = "resources/icon.svg"
app-id = "0x00112233445566778899aabbccddeeff"
version = "0.1.0"
min-keyos-version = "1.0.0"

[publisher]
name = "My Company"
contact-email = "support@example.com"
support-url = "https://example.com/support"

[permissions]
"os/settings" = ["GetDeviceName"]

At build time the CLI emits a manifest.json next to your binary with the resolved permissions, and the kernel enforces exactly what you declared. See Building Apps for the full field reference.

Running on a real device (sideload)

When you're ready to validate on hardware:

foundation sideload              # build, sign, copy to Prime, and launch

foundation sideload:

  1. Runs foundation build to produce a signed app.elf and manifest.json
  2. Finds your mounted PRIME USB volume (/Volumes/PRIME, /media/<user>/PRIME, etc.)
  3. Copies the bundle to apps/<app-name>/ on the device
  4. Pings Prime over the USB control channel and launches your app by app-id

Flags:

  • --release — release build instead of debug
  • --no-run — copy but don't launch
  • --mount-path PATH — override the auto-detected Prime USB mount
  • --serial-port PATH — override the auto-detected USB control port

No store review, no gatekeeping. Sideloading remains supported as a first-class flow.

Do I need a Prime device to start?

No. The hosted simulator (foundation sim) runs the full KeyOS stack on your dev machine — same IPC, same services, same rendering pipeline. You only need a physical device when you're ready to test against real peripherals (NFC, secure element, Bluetooth, camera).

Signing your app

Every app on Prime is signed. foundation build signs the binary in place with cosign2 using a secp256k1 key. To generate your signing identity once:

foundation cert gen "My Company"

This writes private.pem, public.pub, certificate.crt, and cosign2.toml under ~/.foundation/signing/My Company/ and uses it for all future builds unless overridden.

See Building Apps — Signing for the full flow.

Next

  • KeyOS — the operating system your app runs on
  • Building Apps — project structure, manifest format, Slint UI, signing
  • CLI Reference — every command and flag
  • Capabilities — what your app can access