Binnacle Documentation View GitHub Repository

Docs

Set up Binnacle for real Cloudflare data work.

Use this guide to install or build Binnacle, create a least-privilege Cloudflare API token, connect a local workspace, and choose the right workflow for D1, R2, and KV.

Download latest release Start with install
Binnacle D1 query workspace with SQL editor, table rows, and inspector details

Local-first

Your token stays in the OS keychain. Requests go from your machine to Cloudflare.

Install

Use the macOS preview build for the shortest path.

  1. Open the public Binnacle releases page.
  2. Download the latest macOS zip artifact.
  3. Unzip it and open Binnacle Preview.app.
  4. Create a local workspace and paste a scoped Cloudflare API token.
Platform note: The public preview is macOS-first. Do not assume a Windows or Linux build exists unless a release explicitly provides one.

Requirements

Know what the preview expects.

Runtime platform

The public preview is currently macOS-first. Use the release notes for exact architecture and version details for each build.

Cloudflare account

You need a Cloudflare account and an API token scoped to the account and products you want Binnacle to access.

Local credentials

On macOS, tokens are stored in Keychain. Source builds on other desktops require a working local credential store.

Download Safety

Check release artifacts before trusting them with a token.

  1. Download builds only from the public GitHub Releases page.
  2. If the release includes SHA256SUMS.txt, compare the checksum before opening the app.
  3. Check the release notes for the current signing and notarization status before broad distribution.
shasum -a 256 "Binnacle Preview-macos.zip"
Preview builds may be signed differently from a final stable release. If macOS shows an unexpected security warning, verify the artifact source and release notes before entering a Cloudflare token.

Compile

Build from the open-source repository.

Use the source path if you want to audit the code, contribute changes, or run the app directly from a Rust checkout. 

git clone https://github.com/binnacle-app/Binnacle.git
cd Binnacle
cargo check --workspace
cargo test --workspace
cargo run -p binnacle-app --bin binnacle
cargo fmt --all

To create a local macOS app bundle with the Binnacle icon, install cargo-bundle and run the bundle command from the repository root. 

cargo install cargo-bundle --locked
cargo bundle -p binnacle-app --bin binnacle --release --format osx

The desktop app uses Rust and GPUI. A current stable Rust toolchain is expected, and a full macOS GUI toolchain is recommended for native desktop work.

API Token

Create a scoped Cloudflare API token.

Binnacle validates your token with Cloudflare, then stores the token in your OS keychain. The token should grant only the Cloudflare surfaces you plan to use.

  1. Open the Cloudflare dashboard.
  2. For a user token, go to My Profile then API Tokens. For an account-owned token, go to Manage Account then API Tokens.
  3. Create a custom token and give it a clear name such as Binnacle Local Desktop.
  4. Add only the permissions needed for your workflow.
  5. Scope the token to the specific account or resources Binnacle should access.
  6. Optionally restrict the token with IP filtering or an expiry.
  7. Copy the token secret immediately. Cloudflare only shows it once.
Workflow Cloudflare permission Use it for
Workspace label User Details Read Optional profile metadata for a nicer local account label.
D1 read-only D1 Read Database and table browsing where read access is enough.
D1 query or write work D1 Write or dashboard Edit Running SQL that may create, update, delete, or otherwise require write access.
R2 browsing Workers R2 Storage Read Bucket and object listing, previews, and read-only inspection.
R2 object operations Workers R2 Storage Write or dashboard Edit Upload, delete, and other write-level object workflows.
KV browsing Workers KV Storage Read Namespace, key, and value inspection.
KV edits Workers KV Storage Write or dashboard Edit Writing or deleting KV values from the text-first editor.
Least privilege: Start with the narrowest token that matches your work. If a resource does not appear in Binnacle, check the selected Cloudflare account and the token's resource scope before broadening permissions.

Recommended token recipes

Read-only D1

Inspect databases safely.

Use D1 Read when you only need to browse databases, schemas, and table data.

D1 workbench

Run normal SQL work.

Use D1 Write or dashboard Edit when queries may write, migrate, or delete data.

Full preview

Try D1, R2, and KV together.

Add D1 plus R2/KV read or write permissions only for the account and resources you plan to test.

To verify a token manually, use Cloudflare's token verification endpoint: 

curl "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  --header "Authorization: Bearer <API_TOKEN>"

A healthy token should return a successful response with an active status.

References

Cloudflare: Create API token Cloudflare: API token permissions Cloudflare: Restrict tokens

First Run

Connect a local workspace.

  1. Launch Binnacle.
  2. Enter a workspace label if you want a custom local name.
  3. Paste your Cloudflare API token.
  4. Select Connect Account.
  5. Use the sidebar to open D1 databases, R2 buckets, or KV namespaces.

Binnacle stores the token in the OS keychain under the app's credential service. Account metadata, workspace state, panel widths, tabs, and local query history stay on the machine. Binnacle does not require a hosted account or credential relay.

Local Data

Know what stays on your machine.

Token storage

Cloudflare API tokens are stored in the OS credential store, not in the Binnacle repository or website.

Workspace state

Account metadata, tabs, panel widths, and query history are persisted locally so the shell can reopen your workspace.

Logout and reset

Disconnect from inside the app to clear the active local session. For a full reset, remove local app state and the related keychain item.

Token revocation

If a token is exposed or no longer needed, revoke or rotate it in Cloudflare before reconnecting Binnacle.

Usage

Work from the three-panel shell.

D1

Browse live databases, inspect tables and schema, run SQL queries, and keep local query history close to the workspace.

R2

Browse buckets and object catalogs, preview supported objects, upload or download intentionally, and avoid silent overwrites.

KV

Open namespaces, inspect keys, refresh listings, and edit text values without leaving the desktop shell.

Scenarios

Where Binnacle fits naturally.

Repeated database inspection

Keep D1 tables, schema details, and SQL queries in one persistent local workspace for daily application debugging.

Object and content checks

Inspect R2 buckets, preview supported assets, and download exact objects without navigating through dashboard pages.

Small operational edits

Review or update text-first KV values when a deployment, feature flag, or configuration key needs a direct check.

Multi-account context switching

Keep Cloudflare data work in a native tool when browser sessions and dashboard account switching get in the way.

Troubleshooting

Common setup problems.

The token verifies, but resources do not appear.

Check the token's account scope and product permissions. A valid token can still be too narrow to list D1, R2, or KV resources.

The app says the token is inactive.

Return to Cloudflare API Tokens and confirm the token is active, not expired, and not revoked. Create a replacement token if needed.

The local account label looks generic.

Add optional User Details Read permission or enter a workspace label manually during setup.

The token may have been exposed.

Revoke or rotate it in Cloudflare immediately, then reconnect Binnacle with a new scoped token.

Binnacle is an independent third-party tool. It is not affiliated with, endorsed by, or sponsored by Cloudflare.