Tunneler documentation

Governed identities for AI agents. Connect an account you own, and every action your agent takes runs through a verdict, human approval, and a full audit trail before anything leaves.

What is Tunneler

Tunneler lets an AI agent act as a real account on a platform (Reddit, email, more coming) without handing it the keys. You connect an account you own; from then on, every action the agent proposes, replying, posting, DMing, voting, sending email, passes through a governance pipeline: it gets a verdict, risky things wait for your approval, nothing actually sends until you arm it, and everything is written to an append‑only audit log.

The point: you get the usefulness of an autonomous agent on your accounts, with brakes you control and a paper trail for everything.

How it works

One loop, the same for a human in the dashboard or an agent over the API:

1. Connect an owned account (a captured browser session, or email IMAP/SMTP credentials), stored encrypted.
2. Propose an action (reply, post, DM, vote, email). It's saved as a governed draft, never sent yet.
3. Verdict. Guardrails evaluate it and return allow, approval required, draft only, or block.
4. Approve. Anything that needs a human waits in Approvals until you say yes.
5. Execute. Re‑checks the verdict, then sends, but only if external sends are armed. Otherwise it's a safe dry‑run.
6. Audit. The action, its verdict, outcome, and evidence land in the ledger.

Quickstart

Identities

An identity is one account or persona you control. Each carries:

• Platform & handle, e.g. reddit / u/yourname.
• Allowed / blocked actions, the heart of permissions. An action not in allowedActions is refused. Add post and dm only when you want the identity doing those.
• Maturity (new → established → brand), young accounts face stricter approval rules.
• Daily limits and a risk level that feed the guardrails.
• Status, set by health checks: active, needs login / fragile, suspended.

Connecting accounts

Tunneler never stores a master password and never logs in as you with an automation driver. You log in yourself; we capture the resulting session.

One‑click browser login

A real browser opens on a worker and is streamed into your dashboard. You complete the login, including any CAPTCHA or 2FA, exactly like normal. The session is captured the moment you're in, encrypted, and the browser closes. This is the recommended path for Reddit and other social accounts.

Paste or upload cookies

Prefer not to relay a browser? Export your cookies with a "Get cookies.txt" extension (it must include the httpOnly session cookie) and paste or upload them.

Email (IMAP / SMTP)

For an email identity, enter your IMAP host (reading) and SMTP host (sending) plus a username and an app password. Tunneler verifies the IMAP login on save and stores the credentials encrypted. Most providers (Gmail, Fastmail, etc.) require an app‑specific password.

Taking actions

Everything an agent (or you) can do, each governed and audited:

• Reply to a comment, post, or message.
• Post a new top‑level submission (e.g. a Reddit self or link post, with subreddit + title).
• Direct message a user.
• Vote up / down / unvote on a post or comment.
• Email, read the inbox (IMAP) and send / reply (SMTP, with proper threading).

Each one follows propose → verdict → approve → arm → execute. You'll always see a dry‑run preview before anything real happens.

Guardrails & verdicts

Before anything is saved and again before it's sent, the action is evaluated against your policies. The result is one of four verdicts:

• allow — low‑risk and in‑policy. Safe to send.
• approval_required — a human must approve (first posts, sensitive DMs, promo links from young accounts, payments, gray areas).
• draft_only — kept as a draft (e.g. missing context, over a daily limit).
• block — refused, with a reason (action not allowed for the identity, ban/rate‑limit evasion, spam, fake‑customer or banned copy patterns).

Default policies ship with every workspace (help‑first, no fake‑customer claims, no ban evasion, no spam, no em‑dashes). You can review them under Guardrails. Refusing to post is a feature, not a bug.

Approvals & the arm switch

These are your two controls:

• Approvals — anything with an approval_required verdict waits here. You approve or deny, with the full proposal in front of you. Agents are told to stop and report when they hit one; they can't approve their own work.
• The arm switch (top bar, off by default) — the master gate for external sends. While it's off, every "execute" is a dry‑run that shows exactly what would be sent. Flip it on only when you're ready for real sends, and even then risky actions still need approval.

Inbox

Check now pulls fresh inbound items (replies, mentions, DMs, email) for your connected identities. Each item can be triaged, set its status to replied, ignored, escalated, etc., or used to seed a draft via Draft. Agents do the same over the API.

The audit log

The Ledger is append‑only: every proposal, post, block, and approval, with its verdict, outcome, and evidence (permalinks, external ids). It's the record of what your identities did and why, filterable by action type.

Connect an agent

Let Claude Code, OpenClaw, or any agent use your governed identities programmatically. Create a key in Settings → API keys (scopes: read, propose, execute), then connect over MCP or REST. Every action still runs through guardrails, approval, and the arm switch, programmatic never means ungoverned.

MCP (recommended)

claude mcp add tunneler \
  -e TUNNELER_API_KEY=tnl_sk_your_key \
  -- npx tunneler-mcp

Your agent gets tools for the whole loop: tunneler_status, tunneler_list_identities, tunneler_check_inbox, tunneler_list_inbox, tunneler_evaluate, tunneler_propose, tunneler_create_post, tunneler_send_dm, tunneler_vote, tunneler_set_inbox_status, tunneler_list_drafts, tunneler_execute, tunneler_list_approvals, tunneler_audit.

REST API

# list identities
curl https://api.tunneler.ai/api/identities \
  -H "Authorization: Bearer tnl_sk_your_key"

# propose a post (runs guardrails, may open an approval)
curl -X POST https://api.tunneler.ai/api/actions/propose \
  -H "Authorization: Bearer tnl_sk_your_key" -H "content-type: application/json" \
  -d '{"identityId":"reddit-me","actionType":"post","subreddit":"test","title":"Hello","content":"Body"}'

# execute the draft (dry run unless armed)
curl -X POST https://api.tunneler.ai/api/actions/execute \
  -H "Authorization: Bearer tnl_sk_your_key" -H "content-type: application/json" \
  -d '{"draftId":"...","dryRun":true}'

# read the append-only audit log (/api/audit is an alias of /api/actions)
curl "https://api.tunneler.ai/api/audit?limit=30" \
  -H "Authorization: Bearer tnl_sk_your_key"

Full reference at /connect.

Nodes & the public pool

So a workspace's accounts don't all originate from one datacenter IP, you can route an identity's traffic through a residential egress node, a machine you (or a contributor) run.

Run a node

# macOS / Linux (auto-opens a browser to authorize)
npx tunneler-node

# any OS, including Windows
docker run -d --name tunneler-node cgberlin/tunneler-node

On first run it opens an authorization link, approve it while signed in, and the node joins your pool. It only forwards encrypted traffic to Tunneler's supported platforms (enforced on the node itself), opens no inbound ports, and can never read your content or be used as an open proxy.

The pool & points

Toggle a node into the public pool to let other workspaces use it, and earn points whenever their traffic exits through it. Paying plans can draw from the pool when they don't run their own node. See the Nodes tab, including a "what a node can and can't see" breakdown.

Plans

Plans set how many identities a workspace can run (Free 1, Developer 3, Team 15, Growth 60) and who can draw from the shared egress pool. Manage your plan under Settings → Plan.

FAQ

Is this against platform rules?

Tunneler is for accounts you own, acting honestly. The guardrails actively block ban/rate‑limit evasion, spam, and fake‑customer behavior. It is not an account‑farming or evasion tool.

Will anything send by accident?

No. Sends require both an allowing verdict (or a human approval) and the arm switch on. Off by default, every run is a dry‑run.

Can a node operator see my traffic?

No content, it's TLS end‑to‑end and we validate the platform's certificate, so a node can't decrypt or intercept it. A node only sees that it relayed encrypted bytes to a supported platform.

What platforms are supported?

Reddit (reply, post, DM, vote) and email (IMAP read + SMTP send) today. X and LinkedIn are connection/health only for now.

Still stuck? support@tunneler.ai