How to Secure AI Agents on Heroku

SafeClaw by Authensor provides deny-by-default action gating for AI agents running on Heroku. Every action your Claude or OpenAI-powered agent attempts is intercepted and validated against your YAML policy before it executes. SafeClaw runs inside your dyno, requires no add-ons, and has zero external dependencies. Install with npx @authensor/safeclaw and enforce least-privilege for AI agents on Heroku's managed platform.

Prerequisites

• A Heroku account with Heroku CLI installed
• Node.js 18+ (use the heroku/nodejs buildpack)
• An AI agent codebase in a Git repository

Step 1 — Install SafeClaw

npx @authensor/safeclaw

This scaffolds safeclaw.config.yaml and integrates into your agent runtime. MIT-licensed, 446 tests, zero dependencies.

Step 2 — Define a Heroku-Specific Policy

version: 1
defaultAction: deny

rules:
  - action: "file:read"
    path: "/app/**"
    effect: allow

- action: "file:write"
    path: "/tmp/**"
    effect: allow

- action: "network:request"
    host: "api.openai.com"
    effect: allow

- action: "network:request"
    host: "api.anthropic.com"
    effect: allow

- action: "network:request"
    host: "*.herokuapp.com"
    effect: allow
    reason: "Inter-service communication"

- action: "env:read"
    key: "DATABASE_URL"
    effect: deny
    reason: "Agent must not read database credentials"

- action: "env:read"
    key: "HEROKU_*"
    effect: deny
    reason: "Block Heroku platform variables"

- action: "shell:execute"
    effect: deny
    reason: "Shell execution blocked in production"

Heroku deploys your code to /app, so file read permissions are scoped there. Heroku's ephemeral filesystem means /tmp is the only writable location anyway, but SafeClaw makes this explicit in your policy.

Step 3 — Configure the Build

Add SafeClaw initialization to your package.json:

{
  "scripts": {
    "build": "npx @authensor/safeclaw",
    "start": "node agent.js"
  },
  "engines": {
    "node": "20.x"
  }
}

Heroku runs npm run build automatically during deployment.

Step 4 — Create and Deploy the App

heroku create ai-agent-safe
heroku config:set SAFECLAW_AUDIT_SINK=stdout
git push heroku main

SafeClaw runs inside the web dyno. No additional processes or add-ons required.

Step 5 — Protect Config Vars

Heroku Config Vars are exposed as environment variables inside the dyno. An uncontrolled AI agent can read them all. SafeClaw blocks specific keys:

rules:
  - action: "env:read"
    key: "DATABASE_URL"
    effect: deny
  - action: "env:read"
    key: "REDIS_URL"
    effect: deny
  - action: "env:read"
    key: "STRIPE_SECRET_KEY"
    effect: deny
  - action: "env:read"
    key: "SENDGRID_API_KEY"
    effect: deny

Your application reads these at startup. SafeClaw only blocks the AI agent's runtime actions from accessing them.

Step 6 — Worker Dynos

For agents that process background jobs:

# Procfile
web: node server.js
worker: node agent-worker.js

Both processes share the same SafeClaw policy file. The policy is evaluated independently in each dyno.

Step 7 — Docker Deploy (Alternative)

Heroku supports container deployment:

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npx @authensor/safeclaw
CMD ["node", "agent.js"]

heroku container:push web
heroku container:release web

Step 8 — Route Audit Logs via Log Drains

Since Heroku dynos have ephemeral filesystems, route the audit trail through stdout and use a log drain:

heroku drains:add syslog+tls://logs.example.com:6514

SafeClaw's hash-chained audit entries flow through Heroku's log aggregation to your SIEM or log storage. Every action — allowed and denied — is captured with a tamper-proof hash chain.

Verify the Deployment

heroku run npx @authensor/safeclaw audit verify --last 50

This spins up a one-off dyno to verify audit trail integrity.

Related Pages

• Deny-by-Default Explained
• Hash-Chained Audit Logs Deep Dive
• Environment Variable Protection
• API Key Exfiltration Threat