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

# Deploy with clear boundaries

> Protect credentials, tool access, surfaces, and the state that makes an Entity personal.

An Entity's effective access comes from its runtime account, tool configuration, connected services, and exposed surfaces. Configure those boundaries before inviting other people to interact with it.

## Keep secrets on the server

Use a private root `.env` for local development and your hosting platform's secret variables in deployment. Keep provider keys, platform tokens, database credentials, gateway tokens, and shell bridge credentials out of Git.

Shell manifests should reference environment variables or server-side profiles. A browser bundle is public to everyone who can load it; never put a provider credential in a client-side build variable or committed frontend file.

ngram's runtime brain selector accepts credentials for the server-side transport. That does not make every external tool safe to receive those credentials. Give each service a separate, limited key.

## Restrict messaging access

For Telegram, distinguish two lists:

| Variable                          | Purpose                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| `NGRAM_TELEGRAM_ALLOWED_USER_IDS` | People allowed to interact when the access restriction is configured                       |
| `NGRAM_TELEGRAM_OPERATOR_IDS`     | People allowed to use operator controls such as privacy changes, update, pause, and resume |

Obtain your identifier with `/whoami` and set it privately. Review group behavior and bot permissions before adding the Entity to a shared chat. A bot with a message-sending tool can affect people beyond the person currently speaking to it.

## Decide where tools execute

Shell, code, and filesystem tools use the configured execution backend. A remote inference provider does not move tool execution to that provider.

The execution client prefers a configured RPC backend. Local fallback is gated by its configuration and deployment environment. `tools.execution.allow_local` deliberately enables access to the local runtime host; a shell-command denylist is not a sandbox.

Run an agent with powerful tools under a dedicated account or isolated service with only the directories and credentials it needs. Review these capabilities together:

* Shell and code execution.
* Filesystem writes and patching.
* Messaging, social posting, and external service mutations.
* Browser automation and remote desktop access.
* Installed MCP servers and their subprocess environments.

## Protect the spatial connection

The Entity bridge and browser-facing gateway are separate connections. Use the pairing command to generate and coordinate their credentials:

```bash theme={null}
uv run ngram ar setup rook --target local
```

The local lab keeps the Entity bridge on loopback and protects the shared surface with a private bootstrap link and session credential. Share that link only with people you trust to access the Entity. Keep a LAN lab on a trusted network; it is not a general multi-tenant hosting service.

For an internet deployment, use TLS and authenticated access at the gateway and bridge. A tunnel provides connectivity; access policy and bearer-token checks provide authorization.

## Protect memory and backups

Knowledge files, journals, relationship portraits, transcripts, logs, and portable exports may contain private information. A file called `journal.md` is not encrypted merely because it is described as private.

`[locked]` knowledge sections prevent edits through the knowledge-update tool. They do not prevent a process with filesystem access from changing the file.

Keep backups outside the public repository, restrict storage access, and rotate credentials if they were exposed. Follow the application's [security policy](https://github.com/ngramspatial/ngram/blob/main/SECURITY.md) when reporting a vulnerability.