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

Quick Start

Install Binboi, log in, and expose your first local service.

This guide is the shortest trustworthy path from a fresh machine to a working public URL. It assumes you already have a local web service listening on a port such as 3000.

Before you start Install and login First tunnel First request flow What to check next

Preparation

Before you start

You need three ingredients: a running local service, a Binboi dashboard token, and access to the relay you want the CLI to talk to.

Make sure your local app is already reachable on localhost:<port> before you introduce Binboi into the loop.

If the app itself is not healthy, a tunnel will only make that failure public faster.

Typical starting point

A Next.js app on port 3000, an Express API on 8080, or a webhook receiver route inside a local development server are the most common first-use cases.

Step 1

Install the CLI and authenticate once

The first successful Binboi session usually takes less than five minutes when the token flow is already available in the dashboard.

Install and authenticate

bash

brew install binboi/tap/binboi
binboi login --token <dashboard-token>
binboi whoami

1. Install Binboi using the package path that fits your environment.

2. Open the dashboard Access Tokens page and create a token for your machine.

3. Copy the token immediately. The full token is shown only once.

4. Run `binboi login --token <token>` so the CLI can validate the credential and write it to `~/.binboi/config.json`.

5. Run `binboi whoami` to confirm the API URL, token, and local config all agree.

Step 2

Start your first HTTP tunnel

Once you are authenticated, the practical move is to expose one local service with a named subdomain.

Open a public URL for localhost

bash

binboi start 3000 my-app

# Product-facing alias planned
binboi http 3000

The working command in the current repository is `binboi start`. The docs mention `binboi http` because it is the likely long-term ergonomic command shape.

When the agent connects successfully, Binboi prints a public URL and keeps the tunnel session online.

That URL now behaves like a public front door for your local process. Browsers, webhook providers, CI jobs, or teammates can hit it while your app continues to run on your machine.

Step 3

Understand the first successful request flow

A healthy first request confirms more than just network reachability. It proves the token, relay, agent, and local service are all aligned.

Verify the end-to-end path

bash

curl https://my-app.binboi.link/health
curl http://127.0.0.1:3000/health

1. A client hits the Binboi public URL.

2. The relay matches the incoming host to the reserved tunnel record.

3. The relay opens a stream over the connected agent session.

4. The CLI forwards the request to your local service on port 3000.

5. Your app responds, and the response travels back through the same path to the client.

If the public URL fails but localhost works

The problem is usually auth, relay connectivity, or target-port mismatch. It is much less often the provider or browser itself.

Step 4

What to check next

Once the first tunnel is healthy, the best next step depends on what you are building.

If you are receiving callbacks from third parties, move next to the Webhooks guide.

If you need to explain failures or latency, open the Requests and Logs guides.

If the token flow felt confusing, read the Authentication and API Keys guides before scaling to more machines.