Skip to main content

​
Prerequisites

RequirementVersion
Node.js20+
pnpm9+
Gitany recent
Verify your environment before cloning: node --version && pnpm --version

​
Quickstart

1

Clone the repository

git clone https://github.com/sint-ai/sint-protocol.git
cd sint-protocol
2

Install dependencies

pnpm install
This installs all workspace dependencies across the monorepo using pnpm workspaces.
3

Build

pnpm build
Uses Turborepo for parallel builds across the monorepo. Executes 34 build tasks with dependency-aware caching. Subsequent builds are significantly faster due to Turborepo’s local cache.
First build takes ~60–90 seconds. Cached rebuilds complete in under 5 seconds.
4

Run tests

pnpm test
Runs the full test suite: 1,363 tests across all packages. All tests must pass before proceeding. To run tests for a specific package:
pnpm --filter @sint/gateway-server test
5

Start the gateway server

cd apps/gateway-server
pnpm dev
The gateway starts on http://localhost:4100. You should see:
SINT Gateway Server listening on port 4100
6

Verify the gateway is running

curl http://localhost:4100/v1/health
Expected response:
{
  "status": "ok",
  "version": "0.1.0",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
7

Generate a keypair

The gateway uses Ed25519 keypairs for signing capability tokens. Generate one:
curl -X POST http://localhost:4100/v1/keypair
Response:
{
  "publicKey": "ed25519:base64url_encoded_public_key",
  "privateKey": "ed25519:base64url_encoded_private_key",
  "keyId": "key_01HXYZ..."
}
Store the privateKey securely. It cannot be recovered from the gateway. In production, set it via the SINT_API_KEY environment variable and do not expose it in API responses.
8

Create a capability token

A capability token authorizes an agent to perform a specific action on a resource.
curl -X POST http://localhost:4100/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent:my-assistant:v1",
    "resource": "payments:invoices",
    "action": "read",
    "constraints": {
      "maxAmount": 1000,
      "currency": "USD",
      "allowedRegions": ["US", "CA"]
    },
    "tier": "standard",
    "expiresIn": 3600
  }'
Response:
{
  "token": "sint_cap_01HXYZ...",
  "tokenId": "tok_01HXYZ...",
  "agentId": "agent:my-assistant:v1",
  "resource": "payments:invoices",
  "action": "read",
  "constraints": {
    "maxAmount": 1000,
    "currency": "USD",
    "allowedRegions": ["US", "CA"]
  },
  "tier": "standard",
  "issuedAt": "2024-01-01T00:00:00.000Z",
  "expiresAt": "2024-01-01T01:00:00.000Z",
  "signature": "base64url_signature"
}
Token fields:
FieldDescription
agentIdUnique identifier for the agent receiving the capability
resourceThe resource being accessed, in namespace:name format
actionPermitted action: read, write, execute, delete
constraintsArbitrary JSON object enforcing usage limits
tierPolicy tier: standard, elevated, or restricted
expiresInToken TTL in seconds
9

Intercept a request

Before an agent executes an action, the gateway validates its token and records the request in the ledger.
curl -X POST http://localhost:4100/v1/intercept \
  -H "Content-Type: application/json" \
  -d '{
    "token": "sint_cap_01HXYZ...",
    "resource": "payments:invoices",
    "action": "read",
    "context": {
      "requestId": "req_01HXYZ...",
      "agentRuntime": "openai-gpt-4",
      "callerIp": "127.0.0.1"
    }
  }'
Response on success:
{
  "allowed": true,
  "evidenceId": "ev_01HXYZ...",
  "ledgerEntry": {
    "id": "le_01HXYZ...",
    "tokenId": "tok_01HXYZ...",
    "agentId": "agent:my-assistant:v1",
    "resource": "payments:invoices",
    "action": "read",
    "timestamp": "2024-01-01T00:00:00.000Z",
    "result": "allowed"
  }
}
Response on denial (expired token, constraint violation, etc.):
{
  "allowed": false,
  "reason": "TOKEN_EXPIRED",
  "evidenceId": "ev_01HXYZ..."
}
10

Query the evidence ledger

Every intercepted request is recorded in the tamper-evident ledger.
# Get all ledger entries
curl http://localhost:4100/v1/ledger

# Filter by agent
curl "http://localhost:4100/v1/ledger?agentId=agent:my-assistant:v1"

# Filter by token
curl "http://localhost:4100/v1/ledger?tokenId=tok_01HXYZ..."

# Paginate
curl "http://localhost:4100/v1/ledger?limit=50&offset=0"
Response:
{
  "entries": [
    {
      "id": "le_01HXYZ...",
      "tokenId": "tok_01HXYZ...",
      "agentId": "agent:my-assistant:v1",
      "resource": "payments:invoices",
      "action": "read",
      "timestamp": "2024-01-01T00:00:00.000Z",
      "result": "allowed",
      "evidenceId": "ev_01HXYZ...",
      "hash": "sha256:abc123..."
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

​
TypeScript SDK

Install the client library: 
npm install @sint/client
# or
pnpm add @sint/client

import { SintClient } from '@sint/client';

const client = new SintClient({
  gatewayUrl: 'http://localhost:4100',
  apiKey: process.env.SINT_API_KEY,
});

const token = await client.createToken({
  agentId: 'agent:my-assistant:v1',
  resource: 'payments:invoices',
  action: 'read',
  constraints: {
    maxAmount: 1000,
    currency: 'USD',
  },
  tier: 'standard',
  expiresIn: 3600,
});

console.log(token.token); // sint_cap_01HXYZ...

​
sintctl CLI

sintctl is the command-line interface for the SINT Protocol gateway. 
# Install globally
npm install -g sintctl

# Or run via npx
npx sintctl --help

# Create a token
sintctl tokens create \
  --agent "agent:my-assistant:v1" \
  --resource "payments:invoices" \
  --action read \
  --tier standard \
  --expires 3600

# List tokens for an agent
sintctl tokens list --agent "agent:my-assistant:v1"

# Revoke a token
sintctl tokens revoke tok_01HXYZ...

# Inspect a token
sintctl tokens inspect sint_cap_01HXYZ...

​
Environment Variables

Configure the gateway server via environment variables. Copy .env.example to .env in apps/gateway-server/.
VariableRequiredDefaultDescription
SINT_API_KEYYes—Ed25519 private key for token signing. Generate with POST /v1/keypair.
SINT_STORENosqlite://./sint.dbPersistence backend. Supports sqlite://, postgres://.
SINT_CACHENomemory://Cache backend. Supports memory://, redis://host:port.
PORTNo4100Port the gateway listens on.
LOG_LEVELNoinfoLog verbosity: debug, info, warn, error.
CORS_ORIGINSNo*Comma-separated allowed origins for CORS.
Example .env: 
SINT_API_KEY=ed25519:your_base64url_private_key_here
SINT_STORE=postgres://user:pass@localhost:5432/sint
SINT_CACHE=redis://localhost:6379
PORT=4100
LOG_LEVEL=info
CORS_ORIGINS=https://app.example.com,https://api.example.com

​
Docker Deployment

docker run -d \
  --name sint-gateway \
  -p 4100:4100 \
  -e SINT_API_KEY=ed25519:your_key_here \
  -e SINT_STORE=postgres://user:pass@host:5432/sint \
  -e SINT_CACHE=redis://cache:6379 \
  ghcr.io/sint-ai/gateway-server:latest
For production deployments, always set SINT_API_KEY from a secrets manager (AWS Secrets Manager, Vault, Railway secrets). Never hardcode keys in docker-compose files.