Everything you need to understand how Surfit works, how your credentials are protected, and how to connect your systems.
Surfit is the decision layer for AI agent actions. It sits between your agents and the systems they act on — evaluating every action in business context before it reaches any system.
Your agent proposes an action. Surfit evaluates it. Low-risk actions execute automatically. High-risk actions are held for review. Everything gets a tamper-evident receipt.
Surfit is not an orchestrator (it doesn't decide what agents should do), not a guardrail (it doesn't filter model outputs), and not a permissions layer (it doesn't manage who can access what). Surfit decides whether a specific action should happen right now, in this context, with these consequences.
The stack:
Layer 1: Model — make agents smart (Guardrails AI, CTGT, NeMo)
Layer 2: Runtime — make agents safe (IronCurtain, Cisco, CrowdStrike)
Layer 3: Decision — make agents correct (Surfit)
Layer 4: Systems — where agents act (Slack, GitHub, AWS, X, etc.)
From agent action to execution in seconds.
Every action follows the same path:
Key point: The agent never controls execution directly. Surfit controls the execution path. The agent cannot bypass Surfit because it doesn't have direct access to system credentials.
How Surfit protects your credentials and your systems.
Surfit uses a split-authority model. Your credentials are encrypted and managed by Surfit — whether stored in Surfit's credential store or integrated with your own vault. The agent never has access to them.
Every credential access and every action execution is recorded in a hash-chained, append-only audit log.
Global Kill Switch: Halts all execution across all tenants immediately. One command stops everything. No new actions execute until manually re-enabled.
Shadow Mode: Per-tenant evaluate-only mode. Surfit processes every action but executes nothing. Full visibility, zero risk. Learn more →
Surfit's architecture is designed toward SOC 2 Type II compliance:
We are not SOC 2 certified yet. Our architecture follows its control requirements.
Connect your agents to the systems they already use.
Slash commands, channel monitoring, bot posting. Classification by channel type, sensitivity, visibility. Auto-execute for routine team posts, hold for announcements.
POST /api/v1/ingest/slack
Webhook integration for PR events. Classification by target branch and repo sensitivity. PRs to main/production held. Feature branch PRs auto-logged.
POST /api/v1/ingest/github (webhook)
OAuth 1.0a posting via encrypted credentials. Classification by content risk (keywords, URLs, length). Trusted agent sources score lower for routine posts.
POST /api/v1/ingest/x
Page and database action governance. Classification by action type and target sensitivity. Creates auto-execute, deletes on sensitive pages held.
POST /api/v1/ingest/notion
Email governance by recipient and content sensitivity. Internal emails auto-send, external with sensitive content held.
POST /api/v1/ingest/gmail
Same classification as Gmail plus calendar governance. Meeting scheduling, email sending, forwarding.
POST /api/v1/ingest/outlook
Infrastructure action governance. IAM modifications and resource deletions always held. Lambda deploys and S3 updates auto-logged. Production region detection.
POST /api/v1/ingest/aws
How Surfit scores risk and makes decisions.
Every action receives a Wave score from 1 to 5. The score determines whether the action executes automatically or requires review.
| Wave | Level | Handling | Example |
|---|---|---|---|
| 1 | Autonomous | Execute immediately, logged | Agent posts status update to #eng-platform |
| 2 | Logged | Execute with enhanced logging | Agent creates a Notion page for sprint planning |
| 3 | Checked | Execute after context evaluation | Agent deploys Lambda function to staging |
| 4 | Review Required | Held for review | Agent opens PR targeting main on payments repo |
| 5 | Critical | Escalated review | Agent attempts to modify IAM permissions in production |
Wave = System Baseline + Action Modifier + Destination Modifier + Context ModifiersEach system has a base risk level: Slack = 1, GitHub = 2, X = 2, Gmail = 2, AWS = 3
Specific actions add or subtract risk: post_message = +0, merge_pr = +1, modify_iam = +2, draft_email = -1
Where the action targets matters: team channel = +0, company announcement = +2, production branch = +2
Environmental factors: external visibility = +2, sensitive data = +1, irreversible = +1, financial impact = +2
The final score is clamped to 1-5. Every decision is deterministic and explainable. Every receipt includes the full breakdown of factors.
Full evaluation, zero execution. See every decision before going live.
Shadow mode lets you connect a system to Surfit and watch it evaluate your agent's actions — without Surfit executing anything.
When you're comfortable with Surfit's decisions, shadow mode is disabled. Same architecture, same evaluation, same policies — now Surfit executes. No configuration change needed. Just flip the switch.
Why this matters: Shadow mode eliminates the trust leap. You don't have to believe us — you watch the product make decisions on your real workflow, verify it's correct, and then go live when you're ready.
Integrate your agent in minutes.
All requests include a customer ID header:
X-Customer-ID: your-customer-idhttps://your-tenant.surfit.ai/api/v1GET /api/v1/health{"status": "healthy", "version": "3.1.1", "customer_id": "..."}POST /api/v1/ingest/slack
POST /api/v1/ingest/github
POST /api/v1/ingest/x
POST /api/v1/ingest/notion
POST /api/v1/ingest/gmail
POST /api/v1/ingest/outlook
POST /api/v1/ingest/awsPOST /api/v1/ingest/slack
Content-Type: application/json
X-Customer-ID: acme
{
"channel": "eng-platform",
"action": "post_message",
"content": "Deployment v3.1 rolled out to staging",
"user": "deploy-bot"
}{
"id": "slack-a1b2c3d4",
"wave": 2,
"decision": "log",
"action": "post_message",
"system": "slack"
}POST /api/v1/ingest/x
Content-Type: application/json
X-Customer-ID: acme
{
"content": "Post text here",
"actor_id": "marketing-agent",
"source": "openclaw_agent"
}POST /api/v1/governance/evaluate
{
"system": "github",
"action": "merge_pr",
"destination": "main",
"content": "Merge payments refactor",
"context": {"visibility": "company_wide"}
}GET /api/v1/pending — List pending actions
POST /api/v1/pending/{action_id}/approve — Approve action
POST /api/v1/pending/{action_id}/reject — Reject actionGET /api/v1/actions — List recent actions
GET /api/v1/execution-status — Execution state (live/shadow/killed)
GET /api/v1/credentials — Connected systems (metadata only)
GET /api/v1/credentials/rotation-warnings — Credentials older than 90 days
POST /api/v1/credentials/revoke — Revoke system credentialsimport requests
SURFIT = "https://acme.surfit.ai/api/v1"
HEADERS = {"Content-Type": "application/json", "X-Customer-ID": "acme"}
def surfit_action(system, payload):
resp = requests.post(f"{SURFIT}/ingest/{system}", headers=HEADERS, json=payload)
result = resp.json()
if result["decision"] == "approve":
return {"status": "held", "wave": result["wave"]}
return {"status": "executed", "wave": result["wave"]}const SURFIT = "https://acme.surfit.ai/api/v1";
const HEADERS = {"Content-Type": "application/json", "X-Customer-ID": "acme"};
async function surfitAction(system, payload) {
const res = await fetch(`${SURFIT}/ingest/${system}`, {
method: "POST", headers: HEADERS, body: JSON.stringify(payload)
});
return await res.json();
}curl -X POST https://acme.surfit.ai/api/v1/ingest/slack \
-H "Content-Type: application/json" \
-H "X-Customer-ID: acme" \
-d '{"channel": "general", "action": "post_message", "content": "Hello"}'How to migrate on or off Surfit
Surfit holds your system credentials in an AES-256 encrypted store with per-tenant key derivation. However, Surfit is designed so that migrating off is straightforward.
If you decide to stop using Surfit, the migration path is simple:
Your agents construct native API payloads — Surfit does not abstract or normalize the payload format. The agent's integration logic remains the same whether Surfit is in the path or not.
You can revoke any credential at any time through the dashboard or API. Revocation is immediate and permanent — hard delete, not soft delete. The encrypted data is purged from the database, not flagged as inactive.
Key point: Surfit is an execution boundary, not an abstraction layer. Your agent code speaks native system APIs. Surfit evaluates and executes — removing Surfit means your agent calls the system directly instead of through Surfit. The integration logic doesn't change.
How Wave scoring, trust scores, and anomaly detection relate
The Wave engine scores every action using a deterministic formula:
Wave = System Baseline + Action Modifier + Destination Modifier + Context Modifiers (clamped 1-5)This score is computed from the action's metadata — system, action type, destination, and context. It does not use an LLM, does not call an external API, and does not perform inference. The scoring is pure arithmetic.
Agent trust scores track an agent's historical behavior — approval rate, longevity, action volume, rejection rate. A high trust score means the agent has been reliable over time.
However, trust scores never lower the Wave classification of an action. A trusted agent with a score of 95 still receives Wave 5 on modify_iam in production. Wave 5 is Wave 5 regardless of who the agent is.
Trust scores affect:
Trust scores do not affect:
Why this matters: This prevents "long con" attacks where an agent builds trust over time and then uses that trust to bypass governance on a high-risk action. The deterministic boundary is never softened by behavioral history.
How individual scoring, anomaly detection, and correlation rules work together
Surfit evaluates agent behavior at three levels. These layers are hierarchical — they escalate, they do not compete.
Every individual action receives a deterministic Wave score. This is the primary evaluation. Actions scoring Wave 1-3 auto-execute. Wave 4-5 actions are held for operator review.
Surfit monitors agent behavior patterns over time. Anomaly detection flags:
When an anomaly is detected, it surfaces as an alert to the operator. It does not automatically block actions. The Wave engine continues to score normally — the anomaly detection provides additional context for the operator's decision.
Correlation rules detect patterns that span multiple systems. Individual actions may each look safe, but the pattern reveals intent. For example: an agent merges a PR (GitHub), then modifies IAM permissions (AWS), then sends an external email (Gmail) — each action may be Wave 2-3 individually, but the cross-system pattern triggers an escalation.
When a correlation rule fires, the involved actions are escalated to the rule's configured Wave level regardless of their individual scores.
No governance deadlock: These layers do not compete. Wave scoring evaluates individual actions. Anomaly detection surfaces patterns to the operator. Correlation rules escalate specific cross-system sequences. The operator always has final authority — Surfit surfaces information, operators make decisions.