Binboi

Binboi docs

Documentation center

Product docs for tunnels, tokens, webhooks, logs, and the self-hosted control plane.

Getting Started

Introduction Quick Start Installation Authentication

Using Binboi

CLI HTTP Tunnels Requests

Debugging

Webhooks API Keys Logs

Operations

Regions Troubleshooting

Quick path

Install the CLI, create a dashboard token, and open a public URL for `localhost` in minutes.

binboi login --token <token>
binboi start 3000 my-app

HTTP Tunnels

How Binboi exposes localhost over HTTP.

HTTP tunnels are the clearest and strongest current Binboi surface. The relay maps a public host to a connected agent, forwards incoming HTTP traffic to your local target, and keeps enough tunnel context for the dashboard and logs to explain what happened.

HTTP model Public URL mapping Forwarding behavior Common examples MVP limits

Model

How the HTTP tunnel model works

A tunnel is a route plus an active agent connection. When both exist, a public URL can behave like a front door to your local service.

The public relay receives an inbound request and identifies the target tunnel by host.

If the tunnel is active, the relay opens a stream over the existing agent session.

The CLI forwards the request to your local target port and returns the upstream response to the client.

Basic HTTP tunnel

bash

binboi start 3000 marketing-site

# Product-facing alias planned
binboi http 3000

Routing

How public URL mapping works

Binboi primarily routes HTTP traffic by host and subdomain.

Routing concepts

Concept	Meaning	Example
Managed domain	The base domain used by the relay to generate public URLs.	`binboi.link` or `binboi.localhost`
Subdomain	The tunnel-specific label mapped to your service.	`marketing-site`
Public URL	The external URL clients can reach.	`https://marketing-site.binboi.link`
Target	The local HTTP service the CLI forwards traffic to.	`http://127.0.0.1:3000`

Behavior

What forwarding looks like in practice

Once the relay has matched a public URL to an active tunnel, the forwarding behavior should feel simple and predictable.

The relay preserves the original host and adds forwarding headers for upstream context.

The tunnel is considered active only while a live agent session is attached.

If the agent disconnects, the route may remain reserved but traffic will fail until the session returns.

Request counts and transferred bytes can be aggregated at the tunnel level for dashboard reporting.

Examples

Common HTTP tunnel examples

The best early use cases are the ones where deployment would be overkill but public reachability still matters.

Examples

bash

# Local admin tool
binboi start 3000 admin-tool

# Express API
binboi start 8080 internal-api

# Webhook receiver
binboi start 3000 stripe-events

Good first wins

Webhook receivers, staging admin tools, browser-accessible QA previews, OAuth callback routes, and mobile-app callback testing are the best fits for Binboi's current HTTP tunnel model.

MVP limits

Current HTTP tunnel limitations

The docs should describe the working path clearly without pretending the product is broader than it currently is.

HTTP is the strongest runtime path in the repository today.

Path-based routing across multiple local targets is not yet a polished first-class feature.

Raw TCP is still planned and should not be treated as equally mature.

Structured request inspection is evolving from relay events and tunnel metadata rather than a fully finished replay interface.