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

Authentication

Authenticate the CLI with dashboard-issued access tokens.

Binboi separates dashboard identity from CLI credentials. Users create access tokens in the dashboard, then use those tokens with `binboi login` so the CLI can authenticate securely against the backend.

Token model Dashboard flow binboi login Storage and validation Security notes

Model

How access tokens work

The dashboard is where people sign in. The CLI is where machines authenticate. Access tokens are the bridge between those two ideas.

Each token belongs to a user account and should usually represent one machine or workflow.

When the CLI presents a token, the backend validates the token and returns account information through `GET /api/v1/auth/me`.

That same validation model is reused when the agent opens a tunnel session, so login and runtime auth share one coherent story.

Why this split matters

A human signs in to the website. A machine uses a token. That separation makes revocation, auditing, and future RBAC much cleaner than a shared relay secret.

Dashboard

Create a token in the dashboard

The Access Tokens page is the operator-facing source of truth for CLI credentials.

1. Open `/dashboard/access-tokens`.

2. Choose a clear token name such as `M2 MacBook`, `CI smoke runner`, or `payments-staging VM`.

3. Create the token and copy it immediately.

4. Store it locally with `binboi login --token <token>`.

5. Use the dashboard list later to review token prefix, created time, last used time, and status.

One-time reveal rule

The dashboard shows the full token only at creation time. After that, the UI exposes a safe prefix and lifecycle metadata, not the secret itself.

CLI

How `binboi login` works

The login command validates the token first, then writes local auth state if the backend accepts it.

Login and verify

bash

binboi login --token <dashboard-token>
binboi whoami

Token source precedence

Source	When it is used	Why it exists
`--token` flag	Highest priority	Best for copy-paste setup or explicit scripting.
`BINBOI_AUTH_TOKEN`	If no flag is provided	Useful in CI or non-interactive shell environments.
`~/.binboi/config.json`	Fallback	Best for day-to-day local development after one successful login.

Validation

How tokens are stored and validated

Binboi treats access tokens as secrets, not as a normal user-facing string to keep around forever.

The database stores a token prefix and a secure hash, not the raw token.

The CLI stores the raw token locally in `~/.binboi/config.json` so it can authenticate later without asking you to paste the token every time.

The backend compares the presented token against the stored hash after narrowing the search by prefix.

Security

Security notes worth keeping in mind

Token safety is mostly about disciplined handling rather than fancy ceremony.

Use one token per machine or workflow so revocation stays precise.

Do not paste full tokens into screenshots, team chats, or shell history you do not control.

If a token leaks, revoke it in the dashboard immediately and create a new one.

Use `binboi whoami` before debugging tunnel failures so you can rule out auth drift early.