# Permissions

Permissions are a VM option. Pass `permissions` on a call, or on
`createVm`.

## The default

The guest's filesystem, processes, environment, and network stack are fully
virtualized. Guest code can bind listeners and communicate over loopback inside
the VM. External DNS and network connections cross the VM boundary, so they are
denied.

secure-exec/examples/permissions/src/index.ts:

```ts
import { evaluate } from "secure-exec";

const request = `(async () => {
	const response = await fetch("https://example.com");
	await response.text();
	return response.status;
})()`;

// The network is denied unless you allow it.
const denied = await evaluate<number>(request, {
	output: { capture: "stderr" },
});
if (denied.outcome !== "succeeded") {
	console.log(denied.outcome, denied.stderr?.split("\n")[0]); // failed TypeError: fetch failed
}
```

## Grant the network

Your policy is merged over the default. Granting the network leaves every other
scope as it was.

secure-exec/examples/permissions/src/index.ts:

```ts
// VM options such as `permissions` go on the call. A policy is merged over the
// defaults, so granting the network keeps everything else working.
const allowed = await evaluate<number>(request, {
	permissions: { network: "allow" },
});
console.log(allowed.outcome === "succeeded" ? allowed.value : allowed.error); // 200
```

## Allow specific hosts

A rule set denies by default and allows matching patterns. A host needs both a
`dns://` pattern to resolve it and a `tcp://` pattern to connect to it.

secure-exec/examples/permissions/src/index.ts:

```ts
// Allow a single host instead of the whole network.
const scoped = await evaluate<number>(request, {
	permissions: {
		network: {
			default: "deny",
			rules: [
				{
					mode: "allow",
					operations: ["*"],
					patterns: ["dns://example.com", "tcp://example.com:*"],
				},
			],
		},
	},
});
console.log(scoped.outcome === "succeeded" ? scoped.value : scoped.error); // 200
```

## The full policy model

Secure Exec uses the agentOS permission model unchanged: the `fs`, `network`,
`childProcess`, `process`, `env`, and `hostFunction` scopes, rule sets, and
operations. Read the [agentOS permissions reference](/agentos/docs/permissions)
for all of it.