> ## Documentation Index
> Fetch the complete documentation index at: https://nono.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with nono sandboxing in your Node.js application in 5 minutes

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install nono-ts
  ```

  ```bash yarn theme={null}
  yarn add nono-ts
  ```

  ```bash pnpm theme={null}
  pnpm add nono-ts
  ```
</CodeGroup>

## 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`

```bash theme={null}
npm run examples:list
npm run example:all
```

For the guarded apply demos, set `NONO_APPLY=1`.

<Note>
  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.
</Note>

## Basic Usage

### 1. Check Platform Support

Before applying a sandbox, verify that the current platform supports it:

```typescript theme={null}
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:

```typescript theme={null}
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

<Warning>
  Calling `apply()` is **irreversible**. Once applied, the sandbox cannot be weakened or removed for the lifetime of the process.
</Warning>

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="CapabilitySet" icon="list-check" href="/typescript/capability-set">
    Learn all the ways to define capabilities
  </Card>

  <Card title="QueryContext" icon="magnifying-glass" href="/typescript/query-context">
    Test permissions before applying the sandbox
  </Card>

  <Card title="SandboxState" icon="database" href="/typescript/sandbox-state">
    Serialize state for child processes
  </Card>

  <Card title="Functions" icon="code" href="/typescript/functions">
    Module-level functions reference
  </Card>
</CardGroup>