Manifest Reference

manifest.toml is the single source of truth for how a package is built, installed, and run. Every niso package requires one.

Full example#

manifest.toml

1[package]2name = "my-api"3version = "1.0.0"4description = "Production REST API"5license = "MIT"6authors = ["team@example.com"]78[binary]9entrypoint = "my-api"10args = ["--port", "8080"]11working_dir = "/app"1213[runtime]14use = "nodejs:20"15init = true16stop_signal = "SIGTERM"17stop_timeout = "30s"1819[environment]20RUST_LOG = "info"21NODE_ENV = "production"22env_file = "/etc/niso/my-api/.env"2324[service]25user = "app"26group = "app"27restart = "on-failure"28restart_delay = "5s"29after = ["niso-postgres.service"]3031[healthcheck]32http = "http://127.0.0.1:8080/health"33interval = "30s"34timeout = "5s"35retries = 336start_period = "10s"3738[network]39network = "backend"40ports = ["8080:8080", "9090:9090/tcp"]41hostname = "api"42ip = "10.99.1.10"4344[network.policy]45allow_from = ["frontend", "10.0.0.0/8"]46deny_from = []4748[network.policy.egress]49allow = ["postgres.niso.local:5432", "0.0.0.0/0:443"]50deny = []5152[isolation]53preset = "server"5455[isolation.resources]56memory_max = "512M"57memory_high = "384M"58cpu_max = "200%"59pids_limit = 409660shm_size = "64M"61io_weight = 1006263[isolation.resources.ulimits]64nofile = { soft = 65536, hard = 65536 }6566[isolation.security]67seccomp = "default"68capabilities_add = []69capabilities_drop = []70no_new_privileges = true7172[volumes]73data = { mount = "/data", mode = "rw" }74cache = { mount = "/cache", tmpfs = true, size = "256M" }75config = { mount = "/config", host = "/etc/my-api", mode = "ro" }7677[labels]78"niso.proxy.port" = "8080"79"niso.proxy.host" = "api.example.com"8081[hooks]82pre_activate = "scripts/migrate.sh"83post_activate = "scripts/warmup.sh"84on_unhealthy = "scripts/alert.sh"8586[copy]87include = ["dist/", "package.json", "node_modules/"]

[package]#

Required. Package identity and metadata.

Field	Type	Description
`name`	string	Package name. Alphanumeric, hyphens, underscores.
`version`	string	Semver version (e.g., 1.0.0).
`description`	string	Short description shown in registry listings.
`license`	string	SPDX license identifier.
`authors`	string[]	List of author emails or names.

[binary]#

The executable to run.

Field	Type	Default	Description
`entrypoint`	string		Name of the binary to execute (must be in bin/ or on PATH via runtime).
`args`	string[]		Command-line arguments passed to the entrypoint.
`working_dir`	string	`/`	Working directory for the process.

Optional. Declares the language runtime your app needs. The runtime binary is installed once on the host and bind-mounted into the service's isolated rootfs at activation. Your dependencies (node_modules, pip packages, gems) ship inside the package — only the runtime interpreter is on the host.

Field	Type	Default	Description
`use`	string		Runtime specifier: nodejs:20, python:3.12, ruby:3.3, etc.
`init`	bool	`false`	Inject an init process (tini) for proper zombie reaping.
`stop_signal`	string	`SIGTERM`	Signal to send on stop.
`stop_timeout`	string	`10s`	Time to wait after stop signal before SIGKILL.

[environment]#

Environment variables passed to the process.

toml

[environment]RUST_LOG = "info"           # Static variableDATABASE_URL = "..."        # Inline secret (not recommended)env_file = "/etc/niso/my-api/.env"  # File with KEY=VALUE pairs

Tip

Use env_file for secrets. The file is read at service start and its variables are injected without being stored in the manifest.

[service]#

systemd service behavior.

Field	Type	Default	Description
`user`	string		Run as this user. Omit for DynamicUser (recommended).
`group`	string		Run as this group.
`restart`	string	`on-failure`	Restart policy: always, on-failure, never.
`restart_delay`	string	`5s`	Delay before restart.
`stop_timeout`	string	`10s`	Time to wait for graceful shutdown.
`after`	string[]		systemd units this service depends on.

[healthcheck]#

Field	Type	Default	Description
`http`	string		HTTP endpoint to poll. 200-399 = healthy.
`interval`	string	`30s`	Time between checks.
`timeout`	string	`5s`	Maximum time for a single check.
`retries`	number	`3`	Failures before marking unhealthy.
`start_period`	string	`0s`	Grace period after start before checks begin.

[network]#

Network configuration for the service.

Field	Type	Default	Description
`network`	string	`niso-default`	Bridge network to join.
`ports`	string[]		Port mappings: "host:container" or "host:container/proto".
`hostname`	string		DNS name on the network (service-name.niso.local).
`ip`	string		Static IP address (optional, auto-allocated by default).

[network.policy]

Field	Type	Description
`allow_from`	string[]	Services or CIDRs allowed to connect inbound.
`deny_from`	string[]	Services or CIDRs denied inbound.

[network.policy.egress]

Field	Type	Description
`allow`	string[]	Allowed outbound destinations (host:port or CIDR:port).
`deny`	string[]	Denied outbound destinations.

[isolation]#

Field	Type	Default	Description
`preset`	string	`server`	Isolation preset: none, minimal, server, strict, worker, database.

[isolation.resources]

Field	Type	Default	Description
`memory_max`	string		Hard memory limit (e.g., 512M, 2G).
`memory_high`	string		Soft memory limit (throttling threshold).
`cpu_max`	string		CPU quota (100% = 1 core, 200% = 2 cores).
`pids_limit`	number	`4096`	Maximum number of processes.
`shm_size`	string	`64M`	Shared memory size (/dev/shm).
`io_weight`	number	`100`	I/O priority weight (1-10000).

[isolation.security]

Field	Type	Default	Description
`seccomp`	string	`default`	Seccomp profile: default, strict, or path to custom.
`capabilities_add`	string[]		Capabilities to add back (e.g., NET_BIND_SERVICE).
`capabilities_drop`	string[]		Additional capabilities to drop.
`no_new_privileges`	bool	`true`	Prevent privilege escalation.

[volumes]#

Persistent storage and temporary filesystems.

toml

[volumes]# Named volume (managed by niso)data = { mount = "/data", mode = "rw" }# Tmpfs (ephemeral, RAM-backed)cache = { mount = "/cache", tmpfs = true, size = "256M" }# Bind mount from hostconfig = { mount = "/config", host = "/etc/my-api", mode = "ro" }

[hooks]#

Field	Type	Description
`pre_activate`	string	Script to run before activation (e.g., database migrations).
`post_activate`	string	Script to run after successful activation.
`pre_deactivate`	string	Script to run before deactivation.
`post_deactivate`	string	Script to run after deactivation.
`on_unhealthy`	string	Script to run when health check fails.

[labels]#

Arbitrary key-value metadata. Useful for reverse proxy integration, service discovery, and tooling.

[copy]#

Field	Type	Description
`include`	string[]	Files and directories to include in the package.

Note

Use a .nisoignore file (same syntax as .gitignore) to exclude files from the package.

Manifest Reference

manifest.toml is the single source of truth for how a package is built, installed, and run. Every niso package requires one.

Full example#

manifest.toml

1[package]2name = "my-api"3version = "1.0.0"4description = "Production REST API"5license = "MIT"6authors = ["team@example.com"]78[binary]9entrypoint = "my-api"10args = ["--port", "8080"]11working_dir = "/app"1213[runtime]14use = "nodejs:20"15init = true16stop_signal = "SIGTERM"17stop_timeout = "30s"1819[environment]20RUST_LOG = "info"21NODE_ENV = "production"22env_file = "/etc/niso/my-api/.env"2324[service]25user = "app"26group = "app"27restart = "on-failure"28restart_delay = "5s"29after = ["niso-postgres.service"]3031[healthcheck]32http = "http://127.0.0.1:8080/health"33interval = "30s"34timeout = "5s"35retries = 336start_period = "10s"3738[network]39network = "backend"40ports = ["8080:8080", "9090:9090/tcp"]41hostname = "api"42ip = "10.99.1.10"4344[network.policy]45allow_from = ["frontend", "10.0.0.0/8"]46deny_from = []4748[network.policy.egress]49allow = ["postgres.niso.local:5432", "0.0.0.0/0:443"]50deny = []5152[isolation]53preset = "server"5455[isolation.resources]56memory_max = "512M"57memory_high = "384M"58cpu_max = "200%"59pids_limit = 409660shm_size = "64M"61io_weight = 1006263[isolation.resources.ulimits]64nofile = { soft = 65536, hard = 65536 }6566[isolation.security]67seccomp = "default"68capabilities_add = []69capabilities_drop = []70no_new_privileges = true7172[volumes]73data = { mount = "/data", mode = "rw" }74cache = { mount = "/cache", tmpfs = true, size = "256M" }75config = { mount = "/config", host = "/etc/my-api", mode = "ro" }7677[labels]78"niso.proxy.port" = "8080"79"niso.proxy.host" = "api.example.com"8081[hooks]82pre_activate = "scripts/migrate.sh"83post_activate = "scripts/warmup.sh"84on_unhealthy = "scripts/alert.sh"8586[copy]87include = ["dist/", "package.json", "node_modules/"]

[package]#

Required. Package identity and metadata.

Field	Type	Description
`name`	string	Package name. Alphanumeric, hyphens, underscores.
`version`	string	Semver version (e.g., 1.0.0).
`description`	string	Short description shown in registry listings.
`license`	string	SPDX license identifier.
`authors`	string[]	List of author emails or names.

[binary]#

The executable to run.

Field	Type	Default	Description
`entrypoint`	string		Name of the binary to execute (must be in bin/ or on PATH via runtime).
`args`	string[]		Command-line arguments passed to the entrypoint.
`working_dir`	string	`/`	Working directory for the process.

[runtime]#

Field	Type	Default	Description
`use`	string		Runtime specifier: nodejs:20, python:3.12, ruby:3.3, etc.
`init`	bool	`false`	Inject an init process (tini) for proper zombie reaping.
`stop_signal`	string	`SIGTERM`	Signal to send on stop.
`stop_timeout`	string	`10s`	Time to wait after stop signal before SIGKILL.

[environment]#

Environment variables passed to the process.

toml

[environment]RUST_LOG = "info"           # Static variableDATABASE_URL = "..."        # Inline secret (not recommended)env_file = "/etc/niso/my-api/.env"  # File with KEY=VALUE pairs

Tip

Use env_file for secrets. The file is read at service start and its variables are injected without being stored in the manifest.

[service]#

systemd service behavior.

Field	Type	Default	Description
`user`	string		Run as this user. Omit for DynamicUser (recommended).
`group`	string		Run as this group.
`restart`	string	`on-failure`	Restart policy: always, on-failure, never.
`restart_delay`	string	`5s`	Delay before restart.
`stop_timeout`	string	`10s`	Time to wait for graceful shutdown.
`after`	string[]		systemd units this service depends on.

[healthcheck]#

Field	Type	Default	Description
`http`	string		HTTP endpoint to poll. 200-399 = healthy.
`interval`	string	`30s`	Time between checks.
`timeout`	string	`5s`	Maximum time for a single check.
`retries`	number	`3`	Failures before marking unhealthy.
`start_period`	string	`0s`	Grace period after start before checks begin.

[network]#

Network configuration for the service.

Field	Type	Default	Description
`network`	string	`niso-default`	Bridge network to join.
`ports`	string[]		Port mappings: "host:container" or "host:container/proto".
`hostname`	string		DNS name on the network (service-name.niso.local).
`ip`	string		Static IP address (optional, auto-allocated by default).

[network.policy]

Field	Type	Description
`allow_from`	string[]	Services or CIDRs allowed to connect inbound.
`deny_from`	string[]	Services or CIDRs denied inbound.

[network.policy.egress]

Field	Type	Description
`allow`	string[]	Allowed outbound destinations (host:port or CIDR:port).
`deny`	string[]	Denied outbound destinations.

[isolation]#

Field	Type	Default	Description
`preset`	string	`server`	Isolation preset: none, minimal, server, strict, worker, database.

[isolation.resources]

Field	Type	Default	Description
`memory_max`	string		Hard memory limit (e.g., 512M, 2G).
`memory_high`	string		Soft memory limit (throttling threshold).
`cpu_max`	string		CPU quota (100% = 1 core, 200% = 2 cores).
`pids_limit`	number	`4096`	Maximum number of processes.
`shm_size`	string	`64M`	Shared memory size (/dev/shm).
`io_weight`	number	`100`	I/O priority weight (1-10000).

[isolation.security]

Field	Type	Default	Description
`seccomp`	string	`default`	Seccomp profile: default, strict, or path to custom.
`capabilities_add`	string[]		Capabilities to add back (e.g., NET_BIND_SERVICE).
`capabilities_drop`	string[]		Additional capabilities to drop.
`no_new_privileges`	bool	`true`	Prevent privilege escalation.

[volumes]#

Persistent storage and temporary filesystems.

toml

[volumes]# Named volume (managed by niso)data = { mount = "/data", mode = "rw" }# Tmpfs (ephemeral, RAM-backed)cache = { mount = "/cache", tmpfs = true, size = "256M" }# Bind mount from hostconfig = { mount = "/config", host = "/etc/my-api", mode = "ro" }

[hooks]#

Field	Type	Description
`pre_activate`	string	Script to run before activation (e.g., database migrations).
`post_activate`	string	Script to run after successful activation.
`pre_deactivate`	string	Script to run before deactivation.
`post_deactivate`	string	Script to run after deactivation.
`on_unhealthy`	string	Script to run when health check fails.

[labels]#

Arbitrary key-value metadata. Useful for reverse proxy integration, service discovery, and tooling.

[copy]#

Field	Type	Description
`include`	string[]	Files and directories to include in the package.

Note

Use a .nisoignore file (same syntax as .gitignore) to exclude files from the package.