Security

On This Page

• Authentication
• Credential Management
• Network Security
• Rate Limits
• Path Validation
• Security Settings Reference

Authentication

All WebSocket connections must authenticate before sending commands. On first launch, AgentUX auto-generates a 32-character auth token and stores it in the OS credential store.

How it works

1. Client connects to ws://127.0.0.1:9877
2. Client sends agentux.auth as the first JSON-RPC call with the token
3. Server validates the token and marks the connection as authenticated
4. All subsequent requests are processed normally

Auth request example

{
  "jsonrpc": "2.0",
  "method": "agentux.auth",
  "params": { "token": "a1b2c3d4e5f6..." },
  "id": 1
}

Any request sent before authenticating (other than agentux.auth) returns error -32002 (AuthRequired).

Finding your auth token

On first run, the token is logged to the Output Log:

LogAgentUX: Generated auth token: a1b2c3d4... — configure your client with this token

The MCP bridge and Claude CLI receive the token automatically via a temporary credential file. You only need the raw token if connecting custom WebSocket clients.

Disabling authentication

For local development only, you can disable auth in Project Settings > Plugins > AgentUX > Security > Require Authentication. This is not recommended for any shared or networked environment.

Credential Management

AgentUX stores all secrets in the OS credential store — never in environment variables, config files, or plain text.

Managed credentials

• Auth Token — WebSocket authentication (auto-generated)
• Anthropic API Key — for Bridge v2 (pay-per-use mode)
• Neo4j Password — for GraphRAG knowledge base

No environment variable fallbacks

Previous versions read credentials from environment variables as a fallback. This was removed in SEC2. If the credential store is unavailable, the operation fails with an error — no silent fallback to plain text.

Passing secrets to child processes

When AgentUX launches the MCP bridge or Bridge v2, secrets are passed via temporary credential files in a .creds/ directory. Each file is created with restrictive permissions, read once by the child process, and deleted immediately.

Network Security

Localhost-only binding

Both WebSocket servers bind to 127.0.0.1 exclusively:

• Port 9877 — AgentUX plugin (JSON-RPC handler)
• Port 9878 — Bridge v2 (Anthropic API proxy)

This means only processes on the local machine can connect. No firewall rules are needed for local-only operation.

Origin header filtering

Browsers always send an Origin header on WebSocket upgrades. AgentUX rejects connections with non-local origins to prevent cross-site WebSocket hijacking (CSRF). Accepted origins:

• Empty (native clients: wscat, MCP bridge, UE BridgeClient)
• agentux-ue (explicit plugin marker)
• Localhost variants (localhost, 127.0.0.1)

All other origins are rejected with a warning logged to the Output Log.

Remote access

If you need remote access (e.g., headless server), use an SSH tunnel rather than exposing the WebSocket port directly:

ssh -L 9877:127.0.0.1:9877 user@remote-host

Rate Limits

AgentUX enforces per-connection rate limits to prevent accidental or malicious resource exhaustion of the editor process.

Per-connection message rate

Each connection is allowed MaxRequestsPerSecond WebSocket messages per 1-second window (default: 100). Each message counts as one request, regardless of whether it's a single request or a batch.

Batch size cap

JSON-RPC batch arrays are limited to MaxBatchSize elements (default: 50). Batches exceeding this limit are rejected entirely.

Error response

Requests exceeding either limit return error -32006 (RateLimitExceeded):

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32006,
    "message": "Rate limit exceeded"
  },
  "id": null
}

All rate-limited requests are logged with the connection ID for security audit.

Configuring limits

Both limits are configurable in Project Settings > Plugins > AgentUX > Security:

• Max Requests Per Second: 10–1000 (default: 100)
• Max Batch Size: 1–500 (default: 50)

Changes take effect on editor restart.

Path Validation

AgentUX validates all user-provided file paths to prevent unauthorized file access outside the project scope.

Config handler

The editor.config.* methods only accept known INI shorthand names:

• Engine, Game, Input, DeviceProfiles
• GameUserSettings, Scalability, Editor, EditorPerProjectUserSettings

Arbitrary file paths are rejected with error -32005 (PathNotAllowed).

Asset import

The editor.asset.import, editor.asset.reimport, and editor.asset.bulkImport methods validate that source file paths are within:

1. The current project directory, OR
2. Any directory listed in Additional Directories (Settings > Chat > Identity)

Source control

The editor.sourcecontrol.* methods validate that raw disk paths fall within the project directory. UObject package paths (e.g., /Game/Maps/MyMap) are always allowed as they resolve through the engine's own path mapping.

Path traversal protection

All paths are canonicalized before validation: .. sequences are collapsed, relative paths are converted to absolute, and separators are normalized. This prevents traversal attacks like ../../etc/passwd.

Security Settings Reference

All settings are in Project Settings > Plugins > AgentUX > Security.

Additional security-relevant settings in other categories: