Skip to main content

​
Installation

npm install nono-ts

​
Runnable Examples

Use the repository examples for end-to-end runnable flows:
  • /examples/js/01-support-check.js
  • /examples/js/02-build-capabilities.js
  • /examples/js/03-query-policy.js
  • /examples/js/04-state-roundtrip.js
  • /examples/js/05-safe-apply-pattern.js
  • /examples/ts/01-support-check.ts
  • /examples/ts/02-build-capabilities.ts
  • /examples/ts/03-query-policy.ts
  • /examples/ts/04-state-roundtrip.ts
  • /examples/ts/05-safe-apply-pattern.ts
npm run examples:list
npm run example:all
For the guarded apply demos, set NONO_APPLY=1.
The runnable files in examples/ 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 examples/:
  • 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