Skip to main content

​
Installation

npm install nono-ts

​
Runnable Smoke Tests

The repository includes end-to-end scenario scripts under tests/smoke/ in both JavaScript and TypeScript. These also serve as readable usage documentation. 
npm run build:debug
npm test
For the guarded apply demos, set NONO_APPLY=1.
The scripts in tests/smoke/ are the canonical source for end-to-end behavior. This page keeps shorter teaching snippets and links back to those files.

​
Basic Usage

​
1. Check Platform Support

Before applying a sandbox, verify that the current platform supports it: 
import { isSupported, supportInfo } from 'nono-ts';

if (!isSupported()) {
  const info = supportInfo();
  console.error(`Sandboxing not available: ${info.details}`);
  process.exit(1);
}

​
2. Define Capabilities

Create a CapabilitySet and add the permissions your application needs: 
import { CapabilitySet, AccessMode } from 'nono-ts';

const caps = new CapabilitySet();

// Allow read/write access to a directory
caps.allowPath('/var/data', AccessMode.ReadWrite);

// Allow read-only access to system libraries
caps.allowPath('/usr/lib', AccessMode.Read);
caps.allowPath('/lib', AccessMode.Read);

// Allow access to a specific file
caps.allowFile('/etc/ssl/certs/ca-certificates.crt', AccessMode.Read);

​
3. Apply the Sandbox

Calling apply() is irreversible. Once applied, the sandbox cannot be weakened or removed for the lifetime of the process.
import { apply } from 'nono-ts';

// Apply the sandbox
apply(caps);

// From this point forward, the process can only access granted resources

​
End-to-End Patterns

For complete runnable flows, use these scenarios directly from tests/smoke/:
  • 02-build-capabilities for capability construction patterns
  • 03-query-policy for preflight allow/deny checks with QueryContext
  • 04-state-roundtrip for SandboxState serialization and restoration
  • 05-safe-apply-pattern for a guarded irreversible apply() flow
  • 06-10 for wrapper, agent workspace, diagnostics, config roundtrip, and subprocess patterns
  • npm run demo / npm run demo:attack-test for the end-to-end demonstrator

​
Next Steps

CapabilitySet

Learn all the ways to define capabilities

QueryContext

Test permissions before applying the sandbox

SandboxState

Serialize state for child processes

Functions

Module-level functions reference