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
| Form | Declaration | Presentation and backend | SDK / main Agent integration |
|---|---|---|---|
| Static mini app | Omit runtime | Packaged HTML/CSS/JS | Web SDK; business Agent actions need a backend |
| Python worker | managed-worker + python | Static Web UI and managed Python | nexts.backend.invoke; optional declared Agent actions |
| Node worker | managed-worker + node | Static Web UI and managed Node | The same stdio RPC and SDK |
| Native worker | managed-worker + native | Static Web UI and packaged Rust/Go/C/C++ executable | The same stdio RPC; no Python/Node launcher required |
| Managed Web service | managed-web + python / node | Flask/FastAPI/Express provides pages and business APIs | Dedicated WebView; Agent actions use authenticated /_nexts/rpc |
| WASM function | wasm-function + extism | Web UI and bounded computation | nexts_invoke; requires the host adapter feature |
| WASM Component | wasm-component + wasmtime | Web UI and a Component Model module | nexts:app/application@1.0.0; requires host support |
| WASIX | wasix + wasmer | Experimental runtime | Requires the host feature and managed Wasmer; not a general compatibility promise |
| Native desktop app | managed-native | The executable creates its own window | Installation and lifecycle; the current adapter has no Native SDK RPC bridge |
| Remote website | remote-web | Dedicated browser opens an approved HTTPS URL | No local App SDK or Tauri authority by default |
| Installed computer program | Host-created external-installer record | Installed Windows program or user-selected EXE | Shortcut/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-webfor 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-nativecatalog distribution for vendor desktop software and portable EXE/ZIP artifacts. - Use
remote-webfor 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 datanative 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
| Keys | Target |
|---|---|
win32-x64 / win32-arm64 | Windows x64 / ARM64 |
darwin-x64 / darwin-arm64 | macOS Intel / Apple Silicon |
linux-x64 / linux-arm64 | Linux 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.