Packages

A niso package is a compressed tar+zstd archive containing your application, a manifest, and an optional Ed25519 signature.

Creating a package#

Run niso pack in a directory with a manifest.toml. The command creates a .niso file ready for distribution.

bash

$ niso pack  my-api-1.0.0-x86_64.niso (8.2 MB)# Pack with a pre-built binary$ niso pack --binary target/release/my-api# Pack and sign$ niso pack --sign ./niso-signing.key# Custom output path$ niso pack --output /tmp/releases/

Package contents

A .niso file is a zstd-compressed tar archive containing:

my-api-1.0.0-x86_64.niso├── manifest.toml         # Package metadata and configuration├── checksums.sha256      # SHA-256 checksums for all files├── signature.ed25519     # Ed25519 signature (if signed)└── bin/    └── my-api            # Your application binary

.nisoignore

Use a .nisoignore file to exclude files from the package. Same syntax as .gitignore.

.nisoignore

target/node_modules/.git/*.log.env

Signing packages#

Ed25519 signing ensures package integrity and authenticity. Generate a keypair, sign on build, and verify on install.

bash

# Generate signing keypair$ niso keygen --output ./keys/  Created keys/niso-signing.key (private)  Created keys/niso-signing.pub (public)# Sign when packing$ niso pack --sign ./keys/niso-signing.key# Verify on install$ niso install my-api-1.0.0-x86_64.niso --verify-key ./keys/niso-signing.pub

Tip

Add trusted public keys to /etc/niso/trusted-keys/ for automatic verification without the --verify-key flag.

Installing packages#

Installing extracts the package to /opt/niso/packages/name/version/. Multiple versions can coexist.

bash

$ niso install my-api-1.0.0-x86_64.niso  Installed my-api 1.0.0$ niso install my-api-1.1.0-x86_64.niso  Installed my-api 1.1.0

Activating and deactivating#

Activation generates a systemd unit, sets up networking and volumes, and starts the service. Deactivation stops and disables it.

bash

# Activate latest installed version$ niso activate my-api# Activate a specific version$ niso activate my-api 1.0.0# Dry run (show what would happen)$ niso activate my-api --dry-run# Deactivate (stop and disable)$ niso deactivate my-api

Idempotent activation

If the same version is already active and running, niso activate skips the restart. Use --force to restart anyway.

Inspecting packages#

bash

# View metadata without installing$ niso inspect my-api-1.0.0-x86_64.niso# List installed packages$ niso list  NAME      VERSION  STATUS   UPTIME   MEMORY  my-api    1.1.0    active   2h       45 MB  postgres  16.0.0   active   5d       120 MB# List as JSON$ niso list --format json

Rollback#

niso keeps a previous symlink pointing to the last active version. Rollback is instant — no download, no rebuild.

bash

$ niso rollback my-api  Rolled back to 1.0.0  ✓ Service niso-my-api restarted

Removing packages#

bash

# Remove a specific version$ niso remove my-api 1.0.0# Garbage collect old versions (keep current + previous + N)$ niso gc --keep-versions 2

Import and export#

Move packages between machines without a registry.

bash

# Export installed package$ niso export my-api:1.0.0 -o ./my-api.niso# Import on another machine$ niso import ./my-api.niso

Vulnerability scanning#

bash

$ niso scan my-api  No known vulnerabilities found$ niso scan --all  Scanning 5 packages...  my-api      ok  postgres    1 advisory (CVE-2026-1234, low)