# Zones

> Limit what modules can reach through the Instance, such as modules in development or written with AI tools.

URL: https://www.trakhound.com/docs/trakhound-framework/zones

[Security profiles](https://www.trakhound.com/docs/trakhound-framework/security) control what people and API keys can reach. **Zones** control what *modules* can reach. A Zone lists Member modules (APIs, Apps, Functions, Workers, and Services) and Rules for what they can call through their `Client`: APIs, Functions, Workers, Service operations, Volumes, and Instance management. A call that no Rule allows is denied. A module that isn't in any Zone isn't restricted.

> Zones guard against a module reaching something by accident, such as a module in development or one written with an AI coding tool. They are not a security boundary against deliberately hostile code: a module can still use the file system, network, or processes directly. The Zone page flags Members whose Packages do this (**Reaches outside its Client**).

Diagram: A module calls a resource through its Client. If the module isn't in a Zone, the call is allowed. If it is, and a Rule allows the resource and permission, the call is allowed. Otherwise, in Enforce mode the call is denied with 403 Zone Access Denied, and in Audit mode it is allowed but recorded as Would Deny. Both appear in the Zone's Activity, where they can be granted in one click.

## Create a Zone

Open **Config > Zones** in the admin UI and click **Add Zone**. A Zone's page has these sections:

| Section | What you can do |
| --- | --- |
| **Settings** | Name, Description, **Mode**, and **Service Router**. **Enforce** denies calls that aren't allowed; **Audit** allows them but records them as "Would Deny". Members can call each other without a Rule unless you turn that off. |
| **Members** | Add a module, a [Group](https://www.trakhound.com/docs/trakhound-framework/configuration#groups) (`group:{id}`, every module in it, including ones added later), or a pattern such as `worker:dev-*`. A module belongs to only one Zone: the first by ID, and a Zone that lists the module itself comes before one that lists its Group. |
| **Rules** | A Resource, its Permissions (`read`, `write`, `run`; none allows any), and why it's needed. A Resource ending in `*` matches by prefix. |
| **Allowed Callers** | The modules (or `zone:{id}` for every Member of another Zone, or `group:{id}` for every module in a Group) that can call this Zone's Members. Empty allows any module. |
| **Activity** | Calls that were denied, or would be in Audit mode, with counts. **Grant** adds a Rule for exactly that Resource, **Grant All** a broader one, and **Allow Caller** adds the caller to Allowed Callers. |
| **Test a Call** | Choose a Caller, Permission, and Resource, then **Check** to see whether it's allowed and why. |

### Rule Resources

| Example | Allows |
| --- | --- |
| `api:entities:/objects/*` | Calls to the `entities` API under `/objects/` |
| `function:send-report` | Running the `send-report` Function |
| `service:redis:key-values:*` | Any Key-Value operation on the `redis` Service |
| `volume:files:/reports/*` | Files under `/reports/` in the `files` Volume |

## Start in Audit Mode

1. Add the module to a Zone in **Audit** mode.
2. Use the module normally. Calls it makes that no Rule allows appear in **Activity** as "Would Deny".
3. **Grant** what the module needs.
4. Switch the Zone to **Enforce**. A denied call returns `403` ("Zone Access Denied") to the module and is logged.

## Test Data with a Service Router

A Zone's **Service Router** sends every Service call its Members make through that [Router](https://www.trakhound.com/docs/trakhound-framework/routing), whatever Router they ask for. Point it at a Router for test data to try a module in development on a shared Instance without touching production data.

## Module Tokens

A module that runs code in its own process (ex. a Python or Node.js worker) can give that process a **Module Token**, so the process's calls to the System API and APIs are made as the module and its Zone still applies. APIs, Apps, Functions, and Workers create one with `Client.CreateModuleToken()` and start the process with its environment variables:

```
var token = await Client.CreateModuleToken();

var startInfo = new ProcessStartInfo("python", "worker.py");
foreach (var variable in token.GetEnvironmentVariables()) startInfo.Environment[variable.Key] = variable.Value;
Process.Start(startInfo);
```

- The process gets `TRAKHOUND_URL` (the System API), `TRAKHOUND_MODULE_TOKEN`, and `TRAKHOUND_ROUTER_ID`, and sends the token in an `X-TrakHound-Module-Token` header (or `Authorization: Bearer thm_...`). A .NET process can connect with `TrakHoundHttpClient.FromModuleEnvironment()`.
- Tokens are kept in memory and only accepted from the same machine. They stop working when the Instance restarts, when the module is unloaded, after the `lifetime` you pass, or when you call `Client.RevokeModuleToken(token)`.
- They work for the System API and APIs, not App pages or the MCP Server. Calls made with them are not rate limited.

> Behind a reverse proxy on the same machine, list the proxy in [Trusted Proxies](https://www.trakhound.com/docs/trakhound-framework/installation#reverse-proxy), or every request through it counts as coming from the same machine.

## Zone Map

**Config > Zone Map** draws the Zones as a diagram: Callers on the left, Zones with their Members in the middle, and what their Rules allow on the right. Denied calls (red) and Audit calls (amber) appear as they happen; click a line to see its calls and Grant them.

- Drag a module from **Not in a Zone** onto a Zone to add it, drag a Member to another Zone to move it, or back to Not in a Zone to remove it.
- **Arrange**, **Fit**, and **Save Layout** position the diagram. Click a Zone's name to open it.

Each module's configuration page shows the Zone it's in. Zones are stored in the `zone` configuration category and can be included in [Deployments](https://www.trakhound.com/docs/trakhound-framework/configuration#deployments).
