Permissions model

The eight permissions a package can request and how they map to a Low / Medium / High risk level.

Permissions model

Every Nuclexa package declares, up front, exactly what it is allowed to do. There are eight permissions. A package's overall risk level is the highest risk of any single granted permission. This lets you decide whether something is safe to run before it ever touches your machine.

The eight permissions

Permissions are declared as a flat object of booleans in agent.json (or in permissions.json). Any key you omit defaults to false.

json

{
  "permissions": {
    "readFiles": true,
    "writeFiles": false,
    "runCommands": false,
    "network": false,
    "env": false,
    "browser": false,
    "gitHistory": false,
    "secrets": false
  }
}

Permission	Risk	What it allows
`readFiles`	Low	Read files in the workspace.
`gitHistory`	Low	Read commit history and diffs.
`writeFiles`	Medium	Create or modify files in the workspace.
`network`	Medium	Make outbound network requests.
`browser`	Medium	Control a browser session.
`runCommands`	High	Execute commands in your shell.
`env`	High	Read process environment variables.
`secrets`	High	Read configured secrets and tokens.

Risk levels

Low — read-only or otherwise inert. Safe to try.
Medium — can modify files, reach the network, or drive a browser. Reversible but consequential.
High — can run shell commands or read environment variables and secrets. Treat like running an arbitrary script; install only from sources you trust.

How risk is computed

text

risk(package) = max( risk(p) for each permission p that is granted )

So a package requesting only readFiles (Low) is Low risk. Add writeFiles (Medium) and it becomes Medium. Add runCommands (High) and it becomes High — regardless of how many low-risk permissions it also has.

Designing for trust

Start from zero and add only the permissions your package actually exercises.
Prefer readFiles over writeFiles when you only need to analyze.
Avoid runCommands, env, and secrets unless they're genuinely core.
Document non-obvious grants in permissions.json with a reason.

A clean, minimal permission scope is the biggest factor in earning the Security reviewed badge.

The eight permissions

Permissions are declared as a flat object of booleans in agent.json (or in permissions.json). Any key you omit defaults to false.

json

{
  "permissions": {
    "readFiles": true,
    "writeFiles": false,
    "runCommands": false,
    "network": false,
    "env": false,
    "browser": false,
    "gitHistory": false,
    "secrets": false
  }
}

Permission	Risk	What it allows
`readFiles`	Low	Read files in the workspace.
`gitHistory`	Low	Read commit history and diffs.
`writeFiles`	Medium	Create or modify files in the workspace.
`network`	Medium	Make outbound network requests.
`browser`	Medium	Control a browser session.
`runCommands`	High	Execute commands in your shell.
`env`	High	Read process environment variables.
`secrets`	High	Read configured secrets and tokens.

Designing for trust

Start from zero and add only the permissions your package actually exercises.

Prefer readFiles over writeFiles when you only need to analyze.

Avoid runCommands, env, and secrets unless they're genuinely core.

Document non-obvious grants in permissions.json with a reason.

A clean, minimal permission scope is the biggest factor in earning the Security reviewed badge.