JSPM

API gateway for AI agents to access your personal data with human-in-the-loop write approval.

Read requests (GET) execute immediately. Write requests (POST/PUT/DELETE) are queued for human approval before execution.

📖 Read the blog post: How to Let AI Run Your Life Without Giving It Your Keys

How It Works

flowchart LR
    A["🦀 Agent"] -->|read| G["🤖 agentgate"] -->|fetch| S[Services]
    A -->|write| G -->|queue| H["🧑 Human"] -->|approve| S

Supported Services

• GitHub - Repos, issues, PRs, commits
• Bluesky - Timeline, posts, profile (DMs blocked)
• Mastodon - Timeline, notifications, profile (DMs blocked)
• Reddit - Subreddits, posts, comments (DMs blocked)
• Google Calendar - Events, calendars
• YouTube - Channels, videos, subscriptions
• LinkedIn - Profile (messaging blocked)
• Jira - Issues, projects, search
• Fitbit - Activity, sleep, heart rate, profile

Security Notes

IMPORTANT: Do NOT run this service on the same machine as your AI agents (clawdbot, moltbot, openclaw, etc.). If an agent has local access to the agentgate box, it could potentially read the database file directly, bypassing all security controls. Run this gateway on a separate, isolated machine that agents can only reach over the network.

• All write operations require human approval via the admin UI
• Agents cannot approve their own requests
• DMs/messaging endpoints are blocked for social services
• Admin UI is password-protected
• API keys are bcrypt-hashed and only shown once at creation

Quick Start

# Install dependencies
npm install

# Start the server
npm start

# Or with auto-reload for development
npm run dev

The server runs on port 3050 by default. Set PORT environment variable to change it.

First Time Setup

1. Open http://localhost:3050/ui
2. Create an admin password
3. Add service accounts (OAuth or API tokens depending on service)
4. Create API keys for your agents via CLI

Using with Clawdbot / OpenClaw

⚠️ IMPORTANT: Do NOT run agentgate on the same machine as your AI agent (Clawdbot, OpenClaw, etc.). If the agent has local filesystem access, it could read the database directly and bypass all security controls. Always run agentgate on a separate, isolated machine that agents can only reach over the network.

Configure Your Agent

Add agentgate to your agent's TOOLS.md:

### agentgate
- Base URL: `https://your-agentgate-server.com`
- Bearer token: `rms_your_key_here`
- **URL pattern:** `/api/{service}/{accountName}/...`
- **Reads (GET):** Execute immediately
- **Writes (POST/PUT/DELETE):** Queue for human approval

#### Write Queue
# Submit write request
POST /api/queue/{service}/{accountName}/submit
  body: { requests: [{method, path, body}], comment: "why" }

# Check status  
GET /api/queue/{service}/{accountName}/status/{id}

Or include in your agent's system prompt:

You have access to agentgate at https://your-server.com
API key: rms_your_key_here

For reads: GET /api/{service}/{account}/path
For writes: POST to /api/queue/{service}/{account}/submit with {requests, comment}

Always include a clear comment explaining your intent for write operations.
A human will review and approve before execution.

Generate a Skill File

agentgate can generate an AgentSkill compatible file:

curl -H "Authorization: Bearer rms_your_key" \
  https://your-server.com/api/skill > SKILL.md

Webhook Notifications

agentgate can notify your agent when queue items are completed, failed, or rejected — closing the feedback loop so your agent knows immediately when requests are processed.

Setup in Admin UI:

1. Go to Advanced → Clawdbot Notifications
2. Enter your OpenClaw/Clawdbot webhook URL (e.g., https://your-gateway.example.com/hooks/wake)
3. Enter the hooks token from your OpenClaw config
4. Choose events: completed, failed, rejected

Features:

• Real-time notifications — Instant webhook on each approval/rejection
• Notification status — See ✓ notified / ⚠ failed on each queue entry
• Retry individual — Resend failed notifications one at a time
• Batch catch-up — "Retry All" sends missed notifications in one batched message

Webhook payload:

{
  "text": "✅ [agentgate] Queue #abc123 completed\n→ github/monteslu\n→ https://github.com/...\nOriginal: \"Create PR for fix\"",
  "mode": "now"
}

Compatible with OpenClaw's /hooks/wake endpoint. See OpenClaw webhook docs.

Inter-Agent Messaging

Agents can communicate with each other through agentgate, with optional human oversight.

📖 See full documentation

Quick overview:

• Three modes: Off, Supervised (human approval), Open (immediate delivery)
• Configure agent webhooks in Admin UI under API Keys > Configure
• Endpoints: /api/agents/messageable, /api/agents/message, /api/agents/messages, /api/agents/status

Agent Registry

Manage your agents in the admin UI at /ui/keys. Each agent has:

• Name - Unique identifier (case-insensitive)
• API Key - Bearer token for agent → agentgate authentication (shown once at creation)
• Webhook URL (optional) - Endpoint for agentgate → agent notifications
• Webhook Token (optional) - Bearer token for webhook authentication

When an agent's webhook is configured, agentgate will POST notifications for:

• Queue item status changes (approved/rejected/completed/failed)
• Inter-agent message delivery or rejection

Usage

Agents make requests with the API key in the Authorization header:

# Read requests (immediate)
curl -H "Authorization: Bearer rms_your_key_here" \
  http://localhost:3050/api/github/personal/repos/owner/repo

# Write requests (queued for approval)
curl -X POST http://localhost:3050/api/queue/github/personal/submit \
  -H "Authorization: Bearer rms_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"requests":[{"method":"POST","path":"/repos/owner/repo/issues","body":{"title":"Bug"}}],"comment":"Creating issue"}'

API Documentation

Agents can fetch full API documentation at:

GET /api/readme
Authorization: Bearer rms_your_key_here

Self-Hosting

Running as a systemd Service (Linux)

Create /etc/systemd/system/agentgate.service:

[Unit]
Description=agentgate API gateway
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/agentgate
ExecStart=/usr/bin/node src/index.js
Restart=on-failure
RestartSec=10
Environment=PORT=3050
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable agentgate
sudo systemctl start agentgate

Running with Docker

FROM node:20-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 3050
CMD ["node", "src/index.js"]

docker build -t agentgate .
docker run -d -p 3050:3050 -v ./data.db:/app/data.db agentgate

Running with PM2

npm install -g pm2
pm2 start src/index.js --name agentgate
pm2 save
pm2 startup

Remote Access with hsync

The admin UI supports hsync for secure remote access without exposing ports. Configure it in the UI under Configuration > hsync.

Remote Access with Cloudflare Tunnel

Use trycloudflare for quick, free tunnels without a Cloudflare account:

# Install cloudflared
brew install cloudflared  # macOS
# or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

# Start a tunnel (generates a random *.trycloudflare.com URL)
cloudflared tunnel --url http://localhost:3050

For persistent tunnels with a custom domain, create a Cloudflare Tunnel.

Reverse Proxy (nginx)

server {
    listen 443 ssl;
    server_name agentgate.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3050;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Set BASE_URL environment variable to your public URL for OAuth callbacks:

BASE_URL=https://agentgate.yourdomain.com npm start

TODO

• Per-agent service access control - different agents can access different services/accounts
• Fine-grained endpoint control per service - whitelist/blacklist individual endpoints (even for read operations)

License

ISC