NNextsAI Docs

Mini app formats and runtimes

Choose static Web, Python/Node/native workers, managed Web services, WASM, native desktop applications, or remote websites.

Presentation, backend runtime, and distribution are separate choices. A React interface can use a Rust backend. An EXE can also be a complete desktop application that creates its own window; that uses a different adapter.

This guide describes client builds containing native Worker support. If an older host reports unknown variant native, update the host. Updating @nextsai/app-sdk alone cannot add a runtime. A working development server does not establish production-package compatibility.

Supported forms

FormDeclarationPresentation and backendSDK / main Agent integration
Static mini appOmit runtimePackaged HTML/CSS/JSWeb SDK; business Agent actions need a backend
Python workermanaged-worker + pythonStatic Web UI and managed Pythonnexts.backend.invoke; optional declared Agent actions
Node workermanaged-worker + nodeStatic Web UI and managed NodeThe same stdio RPC and SDK
Native workermanaged-worker + nativeStatic Web UI and packaged Rust/Go/C/C++ executableThe same stdio RPC; no Python/Node launcher required
Managed Web servicemanaged-web + python / nodeFlask/FastAPI/Express provides pages and business APIsDedicated WebView; Agent actions use authenticated /_nexts/rpc
WASM functionwasm-function + extismWeb UI and bounded computationnexts_invoke; requires the host adapter feature
WASM Componentwasm-component + wasmtimeWeb UI and a Component Model modulenexts:app/application@1.0.0; requires host support
WASIXwasix + wasmerExperimental runtimeRequires the host feature and managed Wasmer; not a general compatibility promise
Native desktop appmanaged-nativeThe executable creates its own windowInstallation and lifecycle; the current adapter has no Native SDK RPC bridge
Remote websiteremote-webDedicated browser opens an approved HTTPS URLNo local App SDK or Tauri authority by default
Installed computer programHost-created external-installer recordInstalled Windows program or user-selected EXEShortcut/lifecycle management; packages cannot name arbitrary absolute host programs

WASM/WASIX availability depends on the client build. Host application capabilities describe available runtime types. Handle unavailable features in the UI; do not probe private sidecar APIs from an application.

Choosing a runtime

  • Notes, forms, and calculators often need only static Web and SDK storage.
  • Use a worker for private SQLite, durable state, and business tasks. Existing Python/Node projects can retain their language.
  • Use a native worker for an already compiled Rust/Go/C++ core, retaining the Web SDK frontend.
  • Use managed-web for an existing local website and its same-origin APIs.
  • Consider WASM for bounded conversion, computation, and validation; check the ABI and host adapter.
  • Use managed-native catalog distribution for vendor desktop software and portable EXE/ZIP artifacts.
  • Use remote-web for an already deployed online product.

Web UI with a native backend

Web UI → @nextsai/app-sdk → authenticated App Bridge
       → Runtime Manager → stdio JSON-RPC → packaged native worker
                                            → app-private data

native changes how the worker starts. It returns structured business results to a Nexts WebView; it receives no primary account tokens, product database, or general Tauri command access.

managed-native is for programs that create their own windows. Its current business RPC path returns native_sdk_unavailable, so renaming a worker's runtime type does not provide an equivalent integration.

Worker declaration

Python and Node use approved host runtimes with a packaged script entry. A native worker entry is a packaged executable:

{
  "runtime": {
    "type": "managed-worker", "engine": "native",
    "entry": "bin/win32-x64/demo-worker.exe",
    "platforms": { "win32-x64": "bin/win32-x64/demo-worker.exe" },
    "protocol": "nexts-app-rpc-v1", "lifecycle": "on-demand",
    "healthTimeoutMs": 10000, "shutdownTimeoutMs": 5000,
    "resources": {
      "memoryMb": 256, "cpuPercent": 50, "maxProcesses": 1,
      "timeoutMs": 30000, "maxOutputBytes": 4194304
    }
  }
}

Merge this section into .nexts-app/app.json. See the SDK introduction for the frontend manifest and native backend development for a complete example.

Platform selection

KeysTarget
win32-x64 / win32-arm64Windows x64 / ARM64
darwin-x64 / darwin-arm64macOS Intel / Apple Silicon
linux-x64 / linux-arm64Linux x64 / ARM64

platforms is native-worker-only. A nonempty map is exhaustive: an absent current platform fails explicitly, without falling back to entry. Without a map, the literal entry is used for a single-platform package. Nexts does not interpolate {platform}, {arch}, or {exe}. Map values must be real paths. For compatibility, an unused descriptive entry is accepted with a nonempty map; new projects should always use a real entry path.

Every declared artifact must be packaged. Validation checks package containment and executable format: .exe / PE on Windows, ELF on Linux, and Mach-O on macOS. Renaming a script to .exe does not make it a native backend. The OS loader still checks actual architecture, dynamic libraries, signing, and other requirements.

These keys define selection, not certification of every application on every OS. Build and test each advertised platform. Windows resource and process-tree limits use Job Objects; equivalent resource isolation is not promised on other systems.

Managed Web services

{
  "views": [{
    "id": "main", "title": "Local Web", "surface": "window",
    "entry": { "type": "runtime-web", "path": "/" }
  }],
  "runtime": {
    "type": "managed-web", "engine": "python", "entry": "runtime/server.py",
    "port": { "mode": "dynamic", "env": "NEXTS_APP_PORT" },
    "health": { "path": "/health", "timeoutMs": 15000 }
  }
}

Bind to 127.0.0.1 and read NEXTS_APP_PORT; the host also supplies PORT. The WebView opens after the health endpoint succeeds. Legacy fixed ports fail explicitly when occupied. New applications use dynamic ports.

managed-web engines remain Python and Node; native support here is for stdio workers. Package Python dependencies under runtime/python/ at build time. The host never executes pip install, npm install, or package lifecycle scripts during installation or startup.

Data and authority

Version packages are immutable. Write to the assigned data/files/cache/logs paths. Keep a stable app ID across upgrades; uninstall preserves data by default. Applications own their SQLite, migrations, and task records. Nexts owns installation, versions, instances, and grants.

Installation grants the complete declared SDK capability set. optional: true does not create a second consent dialog or toggle. Disable or uninstall to revoke access. Applications must implement explicit business confirmation for destructive changes, external writes, and local-engine startup.

Workers execute trusted code with process limits, not a complete filesystem or network sandbox. Resource limits do not provide WASM isolation. Host APIs enforce permissions per call; worker-native file, network, and subprocess operations must respect the manifest and user selections.

Lifecycle and distribution

An application's windows share one backend and data volume by default. Closing a window detaches the UI. Explicit stop, disable, update, uninstall, and host shutdown stop the backend. on-demand starts on first open/call; persistent workers may be restored at host startup and should be used only when required.

Static Web, workers, and WASM use a standard Nexts ZIP with .nexts-app/app.json at its root. Native desktop apps, remote sites, and external installers use their catalog distribution forms. Installing an application does not register an Agent plugin, skill, or MCP server.

Continue with backend and Agent integration, native backend development, and application management.

On this page