DEV Community

gokul
gokul

Posted on

Giving AI coding agents a public URL — the master-key delegation pattern

#security #ai #webdev #devops

Your AI coding agent needs a public URL for the preview it just built. Most setup guides tell you to paste your API token into the agent's environment. That token can open unlimited tunnels, never expires, and could be exposed if the agent leaks it. There is a safer pattern that has been used across the industry for years.

Full disclosure: I work with 21tunnel, one of the tunneling services that implements this pattern. While the examples use 21tunnel, the security model applies to any tunneling service.

AI coding agents like Claude Code, Cursor, Aider, and Devin increasingly need to expose localhost so developers can test webhooks, preview applications, or share work with teammates. The real challenge isn't tunneling—it's securely delegating permissions to an autonomous agent.

TL;DR

Don't give your AI agent a permanent API token.

Instead:

  • Create a master key.
  • Let the master key mint scoped, short-lived child keys.
  • The AI agent only receives a temporary child key.
  • Child keys expire automatically.
  • If needed, revoke the master key to immediately invalidate every child key it created.

This follows the same security model used by Stripe Restricted Keys, GitHub Fine-Grained Personal Access Tokens, AWS STS, and HashiCorp Vault.

The Problem

Imagine asking Claude Code to:

  • Create a Next.js application.
  • Configure a Stripe webhook.
  • Start the development server.
  • Expose localhost.
  • Share the public URL.

The agent needs credentials to create the tunnel.

There are three approaches:

  1. Give the agent your personal API token.
  2. Create another account for the agent.
  3. Give the agent permission to mint temporary credentials.

The first two provide broad, long-lived permissions.

The third provides only the permissions required for the current task.

Why Permanent Tokens Are Risky

Using a permanent API token introduces several problems:

  • The token may appear in logs or chat transcripts.
  • The token never expires.
  • Revoking it affects every application using it.
  • The token usually has more permissions than the task requires.

The AI agent only needs to create one temporary tunnel—not full account access.

The Master-Key Pattern

The pattern uses three components.

Master Key

  • Long-lived
  • Can mint child keys
  • Cannot directly create or manage tunnels

Child Key

  • Short-lived
  • Limited to one project
  • Automatically expires
  • Cannot mint additional keys

Cascade Revoke

Revoking the master key immediately invalidates every child key created from it.

Benefits

  • Short-lived credentials
  • Project isolation
  • Easy compromise recovery
  • Reduced blast radius

Industry Examples

This isn't a new idea.

Examples include:

  • Stripe Restricted API Keys
  • GitHub Fine-Grained Personal Access Tokens
  • AWS STS AssumeRole
  • OpenAI Service Accounts
  • HashiCorp Vault Dynamic Secrets

All follow the same principle:

Long-lived credentials should only create short-lived credentials.

Creating a Project

mytunnel projects create staging-preview
Enter fullscreen mode Exit fullscreen mode

Example output:

Project created: proj_8f3a2b

Master key:
mtk_master_a1b2c3...
Enter fullscreen mode Exit fullscreen mode

Store the master key securely.

Minting a Child Key

MTK_MASTER=mtk_master_xxxxx \
mytunnel eval mint \
    --project staging-preview \
    --ttl 1h \
    --output-env
Enter fullscreen mode Exit fullscreen mode

Example output:

export MYTUNNEL_AUTH_TOKEN=mtk_child_xxxxx
export MYTUNNEL_PROJECT=staging-preview
Enter fullscreen mode Exit fullscreen mode

The child key:

  • Works only within one project
  • Cannot mint more keys
  • Automatically expires
  • Appears in the audit log

Revoking Everything

mytunnel keys revoke --cascade mtk_master_xxxxx
Enter fullscreen mode Exit fullscreen mode

Output:

Revoked 1 master key.

Revoked 17 child keys.
Enter fullscreen mode Exit fullscreen mode

Example Configuration

Claude Code

.claude/settings.local.json

{
  "env": {
    "MTK_MASTER": "mtk_master_xxxxx"
  }
}
Enter fullscreen mode Exit fullscreen mode

Agent instructions:

When localhost needs to be exposed:

1. Mint a temporary child key.
2. Start the tunnel.
3. Return the public URL.
Enter fullscreen mode Exit fullscreen mode

Cursor

  • Store the master key in a gitignored .env.
  • Add rules instructing the agent to mint a child key before opening a tunnel.

Aider

Store the master key in:

.aider.env
Enter fullscreen mode Exit fullscreen mode

Start with:

aider --env-file .aider.env
Enter fullscreen mode Exit fullscreen mode

Devin

Store the master key as a workspace secret.

Each workspace receives temporary credentials without exposing permanent account access.

Design Decisions

The implementation intentionally avoids:

  • Agent-specific SDKs
  • MCP servers for tunnel management
  • Additional machine-key types
  • IP allowlists for temporary credentials
  • OAuth-based agent authentication

A simple CLI and temporary credentials provide a smaller attack surface while remaining compatible with every AI coding agent.

What Every Tunneling Service Should Provide

A secure delegation system should include:

  • A master key that cannot directly create tunnels.
  • Child keys with enforced expiration.
  • One-step cascade revocation.
  • Project-level isolation.

As AI agents become part of everyday development workflows, developers will increasingly expect temporary, scoped credentials instead of permanent API tokens.

FAQ

Why not give the AI agent my normal API token?

Because permanent tokens provide broad permissions, never expire, and are difficult to revoke selectively.

What is cascade revoke?

A single action that invalidates the master key and every child key created from it.

Can this pattern work without 21tunnel?

Yes.

Any tunneling service can implement scoped temporary credentials. The examples here simply demonstrate one implementation.

Top comments (0)