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

# Authentication and security boundaries

> Grant the minimum required authority and understand what the Engine does and does not isolate.

## Protect the Engine API

The default Engine bind is `127.0.0.1:9321`. Fresh installer-created configurations contain a global auth token, readable only by the service user. CLI commands read it from that user's configuration.

<Warning>
  If `[daemon].auth_token` is absent, the Engine treats requests as local admin and skips authentication. Existing tokenless configurations are not silently changed by upgrades. Never expose a tokenless Engine through a network bind or dashboard proxy apex. Verify authentication before granting remote access.
</Warning>

Keep the Engine API on loopback unless direct network access is intentional. Use encrypted transport for remote bearer tokens. Health checks, API schema/docs, and the internal CA's public certificate are public resources; their availability does not prove authenticated access works.

The App's account login, the Engine's API authorization, and authentication inside a deployed application are separate systems. A [cloud link](/app/) is capped at submitter authority; it is not a remote host-admin credential.

## Issue scoped tokens

| Role        | Authority                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `readonly`  | Permitted reads; content and ownership-sensitive endpoints can impose additional restrictions. |
| `submitter` | Create workloads and manage owned workloads, within scope and quota.                           |
| `admin`     | Manage the Engine, tokens, shared secrets, and cross-owner resources.                          |

As an admin, create a bounded token for an integration:

```bash theme={null}
nerdit token create my-agent --role submitter --scope my-app \
  --expires-in 24h --max-gpus 0 --max-concurrent-jobs 2
nerdit token list
```

Plaintext is shown once. Store it in the client's protected credential configuration. Service scopes restrict writes; they do not bypass ownership. Admin tokens cannot have service scopes. The legacy global configuration token is admin and has no scoped-token row; resources created under it can remain admin-owned.

Creating a token does not switch the CLI to it. When the integration's client is configured with that scoped token, inspect and rotate its own credential:

```bash theme={null}
nerdit token whoami
nerdit token rotate
```

Rotate before expiry and update the client with the new plaintext before its next request. Rotation does not extend expiry unless requested; readonly tokens cannot rotate. An expired token cannot rescue itself through rotation, so an admin must provide a replacement.

From an admin client, revoke a scoped token using the identifier from `token list`:

```bash theme={null}
nerdit token revoke TOKEN_ID
```

The global configuration token has no token row and cannot use self-rotation. A host administrator replaces `[daemon].auth_token` in the protected service-user configuration, restarts the Engine, and updates its clients. Preserve the rest of the file and do not remove the token as an access-recovery workaround: that disables authentication.

Do not print `nerdit token` output into support logs: the command without a subcommand displays the global credential.

## Application secrets

Secrets are encrypted at rest with AES-256-GCM and injected when an application starts. Reads return names, not values:

```bash theme={null}
nerdit secrets list my-app
nerdit secrets rm my-app --key API_KEY
```

The set command takes `KEY=VALUE` arguments. For a non-secret syntax demonstration only:

```bash theme={null}
nerdit secrets set my-app EXAMPLE_KEY=example-value
```

<Warning>
  Real values passed to the CLI can appear in shell history and process arguments. Use an appropriately protected client of the [secret HTTP API](/engine/http-api) when those exposures are unacceptable. Do not paste real credentials into examples, screenshots, logs, Git URLs, or one-off command arguments.
</Warning>

Per-service secrets target an existing service. Reference them from application configuration with `${secrets.API_KEY}`. For a shared secret, an admin uses `--shared` and the application refers to `${secrets.shared.KEY}`. Grant access to shared credentials carefully.

Restart or redeploy an application to pick up changed environment values. Changing a stored managed-database password is not a database password-rotation procedure; the engine's state must agree with its credentials.

Encryption does not protect secrets from the host administrator. Docker access and inspection of a bound container can reveal environment credentials. [Backups](/engine/backup-recovery) containing the master key have the same sensitivity as the secrets themselves.

## Workload and network isolation

The runtime drops capabilities, applies `no-new-privileges`, restricts mounts, and labels containers by Engine instance. These are protective defaults for a trusted host, not a security boundary against an administrator or mutually hostile tenants.

Managed database ports are reachable from containers on the default bridge; database credentials remain the gate. The application proxy, direct loopback port, hosted share, and optional [edge authentication](/engine/networking#add-basic-authentication-at-the-proxy) protect different paths. An edge-auth rule does not remove a local host user's ability to reach a loopback port.

HTTP and MCP share the Engine's roles, quotas, ownership, structured errors, and audit behavior. Enabling HTTP MCP requires both the optional MCP dependency and a configured Engine token. Do not give an agent admin access when a scoped submitter token can perform its work.

## Audit and disclosure

Mutation records omit secret values, but arbitrary application output can still contain sensitive data. Review logs and diagnostics before sharing them. Record error codes and request IDs for support instead of sending credentials.

Report suspected vulnerabilities through the project's published private security reporting channel. Do not open a public issue containing an exploit, credential, or private data. See [support and security reports](/engine/development#support-and-security-reports).