AIP-73: TUNNEL (tunnel/v1): the tunnel provider contract
Fixes the contract a tunnel provider implements to give a locally running service a stable public URL: the TunnelProvider interface (create, list, delete, status, health) with its idempotency rules, the three authentication modes (apiKey, token, oidc), the per-slug credential store under ~/.agentproto/tunnel-creds with its file modes, provider discovery and registration, the lifecycle from setup to delete, the v1 HTTP contract of a remote provisioner (GET/PUT/DELETE /v1/tunnels), and the security and conformance rules.
| Field | Value |
|---|---|
| AIP | 73 |
| Title | TUNNEL (tunnel/v1): the tunnel provider contract |
| Author | Jeremy André <[email protected]> |
| Status | Draft |
| Type | Schema |
| Requires | AIP-1 (process) |
| Composes with | AIP-59 (PAIRING: the end-to-end encrypted path that a plain tunnel does not provide), AIP-60 (SENTINEL: webhook sentinels receive their pushes through a named tunnel) |
| Created | 2026-11-02 |
| Package | @agentproto/tunnel (contract, auth modes, credential store, HTTP client); @agentproto/tunnel-agentik (a provider for the tunnels.agentik.net provisioner) |
Abstract
A tunnel provider exposes a stable public URL for a locally running service. This AIP fixes the provider contract, the authentication modes, the on-disk credential store, provider discovery, the lifecycle every implementation follows, and the HTTP contract of a remote provisioner. A provider is intentionally small: it owns the remote tunnel state and the connector that publishes a local target, and nothing about sessions, apps or routing.
Motivation
The reference runtime ships several tunnel backends inline (quick Cloudflare tunnels, named Cloudflare tunnels, a remote Cloudflare provisioner, ngrok). A third party cannot add a backend without patching the runtime. Fixing the contract as a public primitive gives every backend the same shape, lets a daemon list and query them uniformly, and makes a provider implementable in a package with no dependency on the runtime.
Terminology
| Term | Meaning |
|---|---|
| Provider | An implementation of the TunnelProvider interface, identified by a stable slug. |
| Key | A caller-chosen, stable tunnel identity. It survives restarts and namespaces remote state. |
| Target | The local host:port (and optional protocol) the tunnel forwards to. |
| Connector | The process or sidecar that maintains the tunnel (for example cloudflared). |
| Hostname | A public DNS name routed to the tunnel, primary first. |
| Connector token | A secret the provider returns so the caller can start the connector. Never logged. |
Provider interface
interface TunnelProvider {
readonly slug: string
readonly name: string
readonly capabilities: TunnelCapabilities
create(input: CreateTunnelInput): Promise<TunnelInfo>
list(): Promise<TunnelInfo[]>
delete(key: string): Promise<void>
status(key: string): Promise<TunnelInfo | null>
health(): Promise<TunnelHealth>
}
interface CreateTunnelInput {
key: string
service?: string | null // "http://127.0.0.1:3000", or null to keep the origin
hostnames?: string[] // a request, primary first; empty = assign one
target?: TunnelTarget // convenience; providers may derive service from it
metadata?: Record<string, string> // stored remotely when the provider supports it
}
interface TunnelInfo {
key: string
tunnelId?: string
status: "active" | "starting" | "stopped" | "error" | "unknown"
publicUrl?: string
hostnames: string[]
service?: string | null
createdAt?: string
updatedAt?: string
connectorToken?: string // sensitive
}
interface TunnelHealth {
state: "active" | "degraded" | "error" | "unknown"
reason?: string
checkedAt: string // ISO-8601
latencyMs?: number
hostnames?: Array<{ hostname: string; ok: boolean; reason?: string }>
}
interface TunnelCapabilities {
stableUrl: boolean
autostart: boolean
customDomain: boolean
requiresAuth: boolean
hasApi: boolean
}Rules:
createis idempotent onkey: creating an existing tunnel again updates it and returns the current state.deleteis idempotent: deleting an unknown key is not an error.statusreturnsnullfor an unknown key; transport and auth failures throw.healthreports a state, not an error: an unreachable provider returns{ state: "error" }rather than throwing.statusin the result ofcreatereflects what the provider knows. A provider that cannot confirm the connector is up reportsstarting, notactive.- A provider never logs credentials, connector tokens or full request bodies.
Authentication modes
A configured provider instance uses exactly one auth mode:
| Mode | Shape | Transport | Use |
|---|---|---|---|
apiKey | { mode: "apiKey", apiKey } | Authorization: Bearer <apiKey> | A long-lived key issued by the server (for example sk-...). |
token | { mode: "token", token, expiresAt? } | Authorization: Bearer <token> | A short-lived token supplied by the caller. |
oidc | { mode: "oidc", issuer, clientId, scopes?, accessToken(), logout?() } | Authorization: Bearer <accessToken()> | RFC 8628 device login. |
- In
oidcmode, a401on an authenticated request triggers one token refresh and one retry. A request sent without credentials is never retried that way. - In
tokenmode, a token whoseexpiresAthas passed is not sent: the call fails with an error that says the token expired. - An implementation that accepts more than one mode in its setup fields
documents which one wins.
apiKeySHOULD take precedence overoidc.
Credential store
Provider configuration is stored outside any repository, one file per slug:
~/.agentproto/tunnel-creds/<slug>.json- Directory mode
0700, file mode0600. Both are enforced on every write, including when the directory or the file already exists with a looser mode. - The file is a flat JSON object of setup fields (
baseUrl,apiKey,oidcIssuer,oidcClientId,oidcScopes, ...). apiKey,tokenand any connector token are secrets: never echo them in logs, errors, CLI output or HTTP responses.- A provider may keep refreshed OIDC sessions under
~/.agentproto/tunnel-sessions/<slug>.json; the long-lived API key does not belong there. AGENTPROTO_HOMEoverrides the~/.agentprotoroot.
Discovery and registration
- Slug: lowercase,
^[a-z0-9][a-z0-9._-]*$, unique per host. - Package: first-party providers publish as
@agentproto/tunnel-<slug>and export a provider factory and, optionally, afromTunnelCredentials(record)helper. - Declared metadata:
slug,name,capabilities, and a list of setup fields, each withname,description,requiredandsensitive. - Registration: the daemon discovers installed
@agentproto/tunnel-*packages and validates their declared setup fields before it persists credentials. A provider whose declared fields are invalid is not registered.
The slugs built into the reference runtime are cloudflare-quick,
cloudflare-named, cloudflare-provisioned and ngrok; the reference
package @agentproto/tunnel-agentik adds agentik.
Lifecycle
setup -> auth -> create -> start connector -> health -> stop -> delete- setup: collect the setup fields, validate URLs and slugs, persist
them to
~/.agentproto/tunnel-creds/<slug>.json(0700/0600). - auth: resolve a bearer credential. OIDC may need an interactive
device flow first; the auth state is
pending,logged_inorlogged_out. - create:
PUTthe tunnel identity and the requested hostnames; get back the routed hostnames and a connector token. - start connector: spawn and supervise the provider's connector, with the token in its environment only, never in argv.
- health: probe the public URL or the provider API; report
active,degradedorerror, with per-hostname results. - stop: terminate the connector. Idempotent.
- delete: remove the remote state. Idempotent. It does not stop a connector that is still running unless the caller asked for it.
Starting a tunnel is abort-safe: if stop() lands while create() is in
flight, the provider does not leak a connector, and a caller signal that
is already aborted when a call starts aborts that call before any request
is sent.
HTTP contract (provisioner v1)
A provider backed by a remote provisioner uses these three endpoints. Every
call carries Authorization: Bearer <credential>.
GET {baseUrl}/v1/tunnels
200 { tunnels: [{ key, tunnelId, hostnames, createdAt }, ...] }
PUT {baseUrl}/v1/tunnels/{key}
body { service: "http://127.0.0.1:<port>" | null, hostnames: string[] }
201 (created) or 200 (updated) { tunnelId, hostnames: string[], token }
DELETE {baseUrl}/v1/tunnels/{key}
204, or 404 when the key is unknown (the client treats both as done)keyis URL-encoded. The server namespaces it per caller: two callers using the same key never share a tunnel.hostnamesis a request; the server returns what it actually routed, and may assign its own hostname instead of the requested one.PUTis idempotent and is replayed on every start.- Errors are JSON
{ error, message, checkoutUrl? }:400: invalid key, service or hostname.401: credential invalid or expired (OIDC: refresh once, then prompt).402: payment required;checkoutUrlis shown to the user.409: hostname already taken.429: rate limited, with aRetry-Afterheader in seconds.
Security considerations
- HTTPS only, except for loopback hosts (
localhost,127.0.0.1,[::1]). - Credentials and connector tokens never travel in argv or logs.
- Credential files are
0600; their directory is0700. - A connector token is scoped to one tunnel.
- A provisioner validates
hostnamesandserviceon the server side; it never trusts them as sent. - A public URL is reachable by anyone who has it. A provisioner that guards its tunnels (an access token in the URL, a cookie set on first visit) documents that guard; a tunnel without one is public.
Conformance
An implementation is conformant when:
- It implements every method of
TunnelProvider. createanddeleteare idempotent, andstatusreturnsnullfor an unknown key.healthreturns a state instead of throwing on a transport failure.- Credentials are stored as the credential store section says, with
0700/0600enforced on every write. - No secret appears in error messages, logs, or
TunnelInfoother than the declaredconnectorTokenfield.
AIP-72: MEMORY (memory/v1): typed memory items about a principal and its work
Fixes the stored memory document, one markdown file per memory item: a small typed assertion (user, feedback, project, reference) about a principal or its work, with AIP-10 base fields, a lifecycle (active, then superseded or archived), a lifetime, provenance and capture blocks, and a free markdown body; then the memory store a host reads and writes items through (propose or commit, read, list, search, supersede, archive, compare-and-set, no hard delete) and the projection of items into each harness session (a bounded digest injected natively or through the system prompt, native-memory changes captured back as proposals); then the node and operator anchors, which scope an item's visibility by AIP-34 node and mark its ownership by AIP-9 operator, and the rule that every store operation applies the session's node projection.
AIP-XXXX: DELIVERY-TRIAGE (delivery-triage/v1): triage, ledger and batching between producers and the inbox
Defines the session-delivery stage between any producer and the AIP-46 inbox: deterministic wake, fyi and drop decisions with a non-bypassable always-wake floor, an append-only JSONL triage ledger that never carries payloads, replace-in-place digest batching as ContextSlot N1, silent no-op acknowledgements, and observation-only rollout.