Zones

Limit what modules can reach through the Instance, such as modules in development or written with AI tools.
Framework Docs Menu

Security profiles 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).
A module calls through its Client ex. service:redis:key-values:read or function:send-report
Is the module in a Zone?Members are listed by module or pattern (ex. worker:dev-*)
No → allowed (Zones don't restrict it)
Yes
Does a Rule allow it?Resource (ending in * matches by prefix) and permission
Yes → allowed
No
EnforceDenied: the module gets 403 Zone Access Denied
AuditAllowed, but recorded as Would Deny
Activity and Zone Map Grant adds a Rule for exactly that resource. Start in Audit, grant what the module uses, then switch to Enforce
Zones guard against accidents in modules you're still building, not against deliberately hostile code.

Create a Zone

Open Config > Zones in the admin UI and click Add Zone. A Zone's page has these sections:

SectionWhat you can do
SettingsName, 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.
MembersAdd a module, a Group (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.
RulesA Resource, its Permissions (read, write, run; none allows any), and why it's needed. A Resource ending in * matches by prefix.
Allowed CallersThe 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.
ActivityCalls 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 CallChoose a Caller, Permission, and Resource, then Check to see whether it's allowed and why.

Rule Resources

ExampleAllows
api:entities:/objects/*Calls to the entities API under /objects/
function:send-reportRunning 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, 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, 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.