Common Authensor Configuration Mistakes

Most Authensor setup issues stem from a small set of configuration mistakes. This guide covers the ones the community encounters most frequently, along with their fixes.

Mistake 1: Missing Environment Variables

Authensor's optional features are controlled by environment variables. If Aegis scanning is not working, check that the variable is set:

# Aegis is disabled by default
export AUTHENSOR_AEGIS_ENABLED=true

# Sentinel is also disabled by default
export AUTHENSOR_SENTINEL_ENABLED=true

The control plane will start without these variables but will skip content scanning and behavioral monitoring. No error is logged because the features are intentionally optional.

Mistake 2: Using Admin Keys for Agent Operations

API keys have roles: admin, ingest, and executor. A common mistake is generating an admin key for testing and then deploying it to production. Admin keys bypass certain restrictions. Use executor keys for agents and ingest keys for log submission.

Mistake 3: Fail-Open Default Action

Setting defaults.action: allow in a production policy means any tool not explicitly mentioned in the rules is permitted. This is appropriate for development but dangerous in production. Always use defaults.action: deny for production policies.

Mistake 4: Forgetting the .js Extension in Custom Modules

If you are extending Authensor with custom modules in TypeScript, remember that the project uses ESM with NodeNext module resolution. Imports must include the .js extension:

// Correct
import { evaluate } from './custom-rules.js';

// Incorrect (will fail at runtime)
import { evaluate } from './custom-rules';

Mistake 5: Not Pinning the Policy Version

Policies should be versioned and pinned. If you load policies from a remote source, ensure the agent fetches a specific version, not "latest." A policy change that is correct for one agent might break another.

Mistake 6: Skipping Shadow Mode

Deploying an agent directly to production without a shadow mode period means the first time you learn about policy gaps is when they affect real users. Shadow mode runs the full evaluation pipeline without executing actions, letting you validate the configuration safely.

Mistake 7: Ignoring Hash Chain Verification

Audit trail receipts are hash-chained, but the chain is only useful if you verify it. Schedule regular integrity checks:

npx authensor verify-chain --from <start-receipt-id>

An unverified hash chain is just a log. A verified hash chain is a tamper-evident audit trail.

Review this list whenever you set up a new Authensor deployment. These seven mistakes account for the majority of support questions.