Palaryn

Agent I/O governance for teams that ship AI agents to production.

Palaryn is the control plane between your AI agents and every external service they touch — APIs, databases, filesystems, browsers. One enforcement pipeline for policy, DLP, budgets, rate limits, approvals, and audit. Self-hosted or cloud. Works with Claude, OpenAI, LangGraph, n8n, or any custom orchestrator.

What Palaryn enforces (that prompt injection tools don't):

• Policy — declarative YAML rules: which agents can call which tools, on which domains, at what times
• DLP — secrets, PII, credentials detected and redacted before they leave your perimeter
• Budgets — hard USD spending caps per agent, per task, per team
• Approvals — high-risk actions held for human review before execution
• Rate limits — per-agent, per-tool, configurable windows
• Audit — immutable logs + OpenTelemetry traces to your existing stack (Datadog, Grafana, Elastic)
• Prompt injection detection — multi-layer (regex + LLM classifier), but this is one feature, not the product

Install

curl -fsSL https://app.palaryn.com/install.sh | sh

Or install directly via npm:

npm install -g palaryn

Verify:

palaryn --version
palaryn --help

Quick Start

The fastest way to try Palaryn is a single curl call against the hosted gateway:

curl -X POST https://app.palaryn.com/v1/tool/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "tool": "http.get",
    "input": { "url": "https://api.github.com/repos/octocat/Hello-World" },
    "taskId": "demo-task-1",
    "actorId": "my-agent"
  }'

The response includes the policy decision, DLP scan results, budget report, and the tool output:

{
  "status": "ok",
  "policy": { "decision": "allow", "rule_id": "Allow read operations" },
  "dlp": { "detected": ["email"], "severity": "medium" },
  "budget": { "estimated_cost_usd": 0.001, "remaining_cost_usd_task": 1.999 },
  "output": { "http_status": 200, "body": { "full_name": "octocat/Hello-World", ... } },
  "timing": { "duration_ms": 142 }
}

Integration Methods

Palaryn enforces a single pipeline (auth → rate limit → policy → DLP → budget → execute → audit) with multiple entry points:

| Method | Protocol | Code Change | Best For | |---|---|---|---| | MCP Remote (OAuth) | Streamable HTTP | Zero — one command | Claude Code, Cursor, any MCP client | | MCP Local (stdio) | JSON-RPC stdio | Zero — config only | Local development, offline | | REST API | HTTP POST | Minimal — send JSON | Any HTTP-capable system | | SDK (TypeScript / Python) | HTTP (wrapped) | Import + wrapper | Custom agents, orchestrators | | HTTP Proxy (:3128) | HTTP_PROXY env var | Zero | Containers, K8s, sandbox |

MCP Remote (OAuth) — Recommended

One command, OAuth login in the browser, done:

# Claude Code
claude mcp add --transport http palaryn https://app.palaryn.com/mcp

# Cursor — add to .cursor/mcp.json
{ "mcpServers": { "palaryn": { "url": "https://app.palaryn.com/mcp" } } }

Authentication is fully automatic via OAuth 2.0 (dynamic client registration → browser login → consent → token exchange).

MCP Local (stdio)

Run the gateway locally as an MCP stdio server — no hosted service needed:

# Install + register in one step
npm install -g palaryn
claude mcp add palaryn -- palaryn mcp

Tools exposed: http_request, http_get, http_post — all routed through the full pipeline.

REST API

curl -X POST https://app.palaryn.com/v1/tool/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "tool": "http.post",
    "input": { "url": "https://httpbin.org/post", "body": { "key": "value" } },
    "taskId": "my-task",
    "actorId": "my-agent"
  }'

The API also accepts the full ToolCall schema for advanced use cases (explicit tool_call_id, actor, source, tool, args).

HTTP Forward Proxy

Zero-code integration — set an environment variable and all outbound HTTP flows through Palaryn:

export HTTP_PROXY=http://WORKSPACE_ID:API_KEY@gateway:3128
export HTTPS_PROXY=http://WORKSPACE_ID:API_KEY@gateway:3128

# All HTTP traffic now goes through Palaryn automatically
curl https://api.github.com/repos/octocat/Hello-World

Requires PROXY_ENABLED=true on the gateway.

Self-Hosted Setup

Prerequisites

• Node.js 20+
• npm

From Source

git clone https://github.com/palaryn-ai/palaryn.git && cd palaryn
npm install
npm run build
npm start

The gateway starts on port 3000. Verify: curl http://localhost:3000/health

Docker Compose (Full Stack)

# Gateway + Redis + Postgres + Jaeger
docker compose up

# With dev hot-reload
docker compose --profile dev up

CLI Commands

| Command | Description | |---|---| | palaryn start | Start the gateway server | | palaryn mcp | Start MCP stdio server | | palaryn --help | Show all options |

Key Features

Security & DLP

• Policy engine — YAML DSL with allow/deny/require-approval rules, domain allowlists, capability-level gating (read/write/delete/admin)
• DLP scanning — Entropy-based and pattern-based detection of secrets (API keys, JWTs, tokens) and PII (emails, phone numbers) in both requests and responses
• Prompt injection defense — Three-layer detection: regex patterns (36+ patterns, text normalization), heuristic structural scorer (6 signals, multilingual EN/PL/DE/ES/FR/RU), and LLM classifier (sandwich defense, 7 attack categories)
• Redaction — Mask, hash, drop, or tokenize sensitive data before it leaves the gateway
• Approval workflows — Asynchronous, signed, time-bound approvals for risky operations
• SSRF protection — DNS validation, IP pinning, private address blocking
• RBAC — Role-based access control with per-workspace API keys and scoped permissions

Cost & Budget Controls

• Granular budgets — Per-task, per-user, per-workspace, and per-tool spending limits with hard stops
• Rate limiting — Configurable per-actor and per-workspace request rate limits
• Response caching — TTL-based caching of GET responses and idempotent call deduplication
• Anomaly detection — Rolling baselines with z-score anomaly flagging

Audit & Integrations

• Immutable audit log — Append-only event log for every stage of the pipeline
• Full traceability — Correlation via task_id and tool_call_id across the tool call lifecycle
• OpenTelemetry export — Rich per-step spans with GenAI semantic conventions — pipe enforcement data to Datadog, Grafana, Elastic, or any OTel-compatible backend
• Prometheus metrics — 18 metric types (latency, error rate, cost, tokens, DLP detections, policy decisions)
• Webhook alerting — Real-time alerts for DLP detections, budget thresholds, policy denials, and anomalies

Project Structure

/
├── src/
│   ├── server/            # Express gateway server + request orchestration
│   ├── mcp/               # MCP bridge (stdio + HTTP Streamable + OAuth 2.0 provider)
│   ├── policy/            # Policy engine (YAML DSL evaluation)
│   ├── dlp/               # DLP scanner (secrets, PII, prompt injection — 3-layer defense)
│   ├── budget/            # Budget manager (per-task/user/org budgets, hard stops)
│   ├── audit/             # Audit logger (immutable event log, trace reconstruction)
│   ├── executor/          # HTTP executor (retries, backoff, caching, SSRF protection)
│   ├── approval/          # Approval manager (JWT tokens, time-bound approvals)
│   ├── auth/              # Authentication (login, session, OAuth providers)
│   ├── saas/              # SaaS routes (workspaces, API keys, dashboard, events)
│   ├── admin/             # Admin routes (config, API keys, policy management)
│   ├── billing/           # Stripe billing (subscriptions, plan enforcement)
│   ├── proxy/             # HTTP forward proxy (CONNECT tunneling)
│   ├── middleware/        # Auth, validation, rate limiting, RBAC middleware
│   ├── storage/           # Storage backends (memory, PostgreSQL, Redis)
│   ├── metrics/           # Prometheus metrics
│   ├── tracing/           # OpenTelemetry tracing
│   ├── config/            # Default configuration + startup validation
│   ├── types/             # Canonical schemas (ToolCall, ToolResult, Policy, Config)
│   └── index.ts           # Package exports
├── web/                   # React SPA frontend (dashboard, docs, onboarding)
├── sdk/typescript/        # TypeScript SDK client
├── sdk/python/            # Python SDK (sync + async clients)
├── policy-packs/          # Pre-built YAML policy configurations
├── tests/
│   ├── unit/              # 2600+ unit tests across 67 test suites
│   └── integration/       # Integration tests (auto-skip without Redis/Postgres)
├── Dockerfile             # Multi-stage production Docker build
├── docker-compose.yaml    # Docker Compose (Gateway + Redis + Postgres + Jaeger)
└── package.json

Development

Commands

| Command | Description | |---|---| | npm install | Install dependencies | | npm run build | Compile TypeScript to dist/ | | npm start | Start in production mode (requires build) | | npm run dev | Start in development mode (ts-node, no build needed) | | npm test | Run all tests | | npm run test:unit | Run unit tests | | npm run test:integration | Run integration tests |

Environment Variables

| Variable | Default | Description | |---|---|---| | PORT | 3000 | Server listen port | | NODE_ENV | development | Environment (development / production) | | AUTH_ENABLED | true | Enable authentication | | POLICY_PACK_PATH | ./policy-packs/default.yaml | Active policy pack | | AUDIT_LOG_DIR | ./logs | Audit log directory | | JWT_SECRET | (required in prod) | JWT signing secret | | APPROVAL_SECRET | (required in prod) | Approval workflow secret | | OAUTH_SESSION_SECRET | (required in prod) | Session cookie secret | | REDIS_URL | -- | Redis connection URL | | DATABASE_URL | -- | PostgreSQL connection URL | | PROXY_ENABLED | false | Enable forward proxy on port 3128 | | FRONTEND_ENABLED | false | Serve React SPA frontend | | MCP_OAUTH_ENABLED | false | Enable MCP OAuth 2.0 provider | | MCP_OAUTH_BASE_URL | -- | Base URL for MCP OAuth | | STRIPE_SECRET_KEY | -- | Stripe API key for billing |

Policy Packs

Policy packs are YAML files that define security rules, domain allowlists, and approval requirements:

| Pack | File | Description | |---|---|---| | Default Safe | policy-packs/default.yaml | Reads allowed, writes need approval, deny delete/admin | | Dev Fast | policy-packs/dev_fast.yaml | Permissive reads and writes for development | | Prod Strict | policy-packs/prod_strict.yaml | Minimal permissions for production |

rules:
  - name: "Require approval for write operations"
    effect: REQUIRE_APPROVAL
    priority: 20
    conditions:
      capabilities: ["write", "delete", "admin"]
    approval:
      scope: "team_lead"
      ttl_seconds: 3600

API Endpoints

| Method | Endpoint | Description | |---|---|---| | POST | /v1/tool/execute | Execute a tool call through the gateway | | POST | /v1/tool/approve | Approve or deny a pending action | | GET | /v1/tasks/{id}/trace | Retrieve the full trace for a task | | GET | /v1/policies/current | Get the active policy configuration | | POST | /v1/policies/validate | Validate a policy before deployment | | GET | /v1/approvals/pending | List pending approval requests | | POST | /mcp | MCP Streamable HTTP endpoint (OAuth 2.0) | | GET | /health | Health check | | GET | /ready | Readiness probe (for K8s) | | GET | /metrics | Prometheus metrics |

All endpoints (except /health, /ready, /metrics) require authentication via X-API-Key header or Bearer token.

Architecture

Agents / Orchestrators
  (Claude Code, Cursor, LangGraph, n8n, custom)
            │
            │  MCP / REST API / HTTP Proxy
            ▼
┌──────────────────────────────────────┐
│           Palaryn Firewall            │
│  ┌──────┬───────┬─────┬──────┬─────┐│
│  │ Auth │ Rate  │ DLP │Policy│Budgt││
│  │      │ Limit │     │      │     ││
│  └──┬───┴───┬───┴──┬──┴───┬──┴──┬──┘│
│     │       │      │      │     │   │
│     ▼       ▼      ▼      ▼     ▼   │
│  Executor  Audit  Metrics Traces    │
└──────────────┬───────────────────────┘
               │
               ▼
  External World / Internal Services
  (SaaS APIs, databases, Git, Slack)

Every tool call flows through: Auth → Rate Limit → DLP (args) → Policy → Budget → Execute → DLP (output) → Audit → Return.

Tech Stack

| Layer | Technology | |---|---| | Gateway | Node.js / TypeScript, Express | | Frontend | React SPA (Vite, Tailwind, Recharts) | | Policy DSL | YAML with OPA/Rego engine | | Storage | In-memory (dev), PostgreSQL (prod), Redis (rate limiting + caching) | | Auth | API keys, JWT/OIDC, OAuth 2.0 (MCP), RBAC | | Observability | OpenTelemetry (OTLP), Prometheus metrics | | MCP | JSON-RPC 2.0 over stdio + HTTP Streamable transport | | SDKs | TypeScript SDK, Python SDK (sync + async) | | Billing | Stripe (subscriptions, usage metering) | | Deployment | Docker Compose (Gateway + Redis + Postgres + Caddy) |

Documentation

Full documentation is available at app.palaryn.com/docs and in the docs/ directory.

| Document | Description | |---|---| | ARCHITECTURE.md | Full technical architecture | | INDEX.md | Product documentation index | | constraints.md | Coding patterns and invariants |

"Your agents can use tools. Under your rules."