Quickstart

Quickstart

Get AgentSec running locally in 5 minutes with Docker Compose.

Prerequisites

  • Docker and Docker Compose
  • A Telegram bot token (create one via @BotFather)
  • The chat ID where approval messages should go (use @userinfobot or a group chat ID)

1. Clone and Copy Example Files

git clone https://github.com/anthropics/agentsec.git
cd agentsec
cp agentsec.example.yaml agentsec.yaml
cp local.env.example .env

2. Generate Secrets and Fill In .env

Generate an encryption key and agent API keys:

# Encryption key (used for HMAC-SHA256 agent auth)
openssl rand -hex 32
 
# Agent API keys (one per agent)
openssl rand -hex 32   # for openclaw
openssl rand -hex 32   # for research-bot

Edit .env with the generated values and your Telegram credentials:

AGENTSEC_ENCRYPTION_KEY=<paste-64-hex-chars>
TELEGRAM_BOT_TOKEN=<your-bot-token>
TELEGRAM_CHAT_ID=<your-chat-id>
AGENTSEC_AGENT_KEY_OPENCLAW=<paste-64-hex-chars>
AGENTSEC_AGENT_KEY_RESEARCH_BOT=<paste-64-hex-chars>
AGENTSEC_CRED_TWITTER_HOLONYM=<your-twitter-bearer-token>
AGENTSEC_CRED_GMAIL_HOLONYM=<your-gmail-oauth-token>
AGENTSEC_CRED_OPENAI_KEY=<your-openai-key>

3. Start the Proxy

docker-compose -f docker-compose.yaml -f docker-compose.local.yaml up --build

The proxy listens on http://localhost:3100. No TLS in local mode.

4. Send a Test Request

Using the unified interface (recommended):

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $AGENTSEC_AGENT_KEY_OPENCLAW" \
  -H "X-AgentSec-Credential: twitter-holonym" \
  -H "X-AgentSec-Target: https://api.twitter.com/2/users/me" \
  -H "X-AgentSec-Method: GET"

Since the policy auto-approves GET requests for twitter-holonym, this returns immediately with the API response.

5. Try a Write Request

curl -X POST http://localhost:3100/forward \
  -H "X-AgentSec-Key: $AGENTSEC_AGENT_KEY_OPENCLAW" \
  -H "X-AgentSec-Credential: twitter-holonym" \
  -H "X-AgentSec-Target: https://api.twitter.com/2/tweets" \
  -H "X-AgentSec-Method: POST" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from AgentSec!"}'

This time the proxy sends an approval request to your Telegram chat. You’ll see the full request details and can tap Approve or Deny. The curl command blocks until you respond (up to 5 minutes by default).

6. Check Available Services

Agents can discover what credentials they have access to:

curl http://localhost:3100/agent/services \
  -H "X-AgentSec-Key: $AGENTSEC_AGENT_KEY_OPENCLAW"

What just happened? The proxy authenticated your agent via X-AgentSec-Key, looked up the credential by name, checked the policy (GET = auto-approve, POST = require approval), waited for your Telegram approval on the write, injected the real API key into the Authorization header, forwarded the request, and scrubbed any credential values from the response. See How It Works for the full flow.

Your agent’s code barely changes. Any skill or tool that makes API calls works the same way — just use a credential name where you’d normally put a raw secret. The agent doesn’t need to know whether a credential is an API key, an OAuth token, or something custom. The proxy abstracts that away.

Next Steps

IntroductionHow It Works