Connecting to a Dolt Server

Beadbox can connect to a running Dolt SQL server, giving you multi-writer access and team workflows on top of the same beads databases you use from the CLI.

Requires Beadbox 0.9.12+ Check your version in Settings > About or at /api/version.

Prerequisites

Before you start, you need three things running:

Component	Minimum Version	Check
beads CLI (`bd`)	0.56.x+	`bd --version`
Dolt server	Running and accepting connections	`dolt sql-server` in your project
Beadbox	0.9.12+	Settings > About

Your Dolt server must have at least one database following the beads_ naming convention. This is what beads creates when you run bd init with Dolt mode. Beadbox uses this prefix to discover beads databases and ignore unrelated ones.

Quick Start (local, no auth)

The fastest path: a Dolt server on your own machine with no authentication configured.

1. Start your Dolt server

cd ~/Projects/myproject
dolt sql-server

Dolt listens on port 3307 by default.

2. Open Beadbox

On the workspace selector, click Add by server (or find the Advanced card on the welcome screen if this is your first launch).

3. Enter connection details

Host	`127.0.0.1` (pre-filled)
Port	`3307` (pre-filled)
User	`root` (pre-filled)
Password	leave empty
TLS	unchecked

4. Click "Discover Databases"

Beadbox connects to the server and runs SHOW DATABASES to find all databases matching the beads_* pattern.

5. Select databases

The discovery screen lists every beads database found on the server. Check the ones you want to add as workspaces. Each gets a local directory path.

6. Click "Add Workspaces"

Beadbox creates the local .beads/ directory with a metadata.json pointing at your server, registers the workspace, and opens it.

You're connected. Changes made via bd on the CLI or by other team members writing to the same Dolt server will appear in Beadbox within a few seconds (server mode polls for changes at 1-second intervals).

Connecting with Authentication

If your Dolt server requires a username and password:

Follow the same steps as Quick Start, but fill in the User and Password fields with your Dolt server credentials.
If TLS is required (common for remote servers), check the Use TLS checkbox.
Click Discover Databases and proceed with discovery.

How passwords are handled

Passwords are held in memory only. Beadbox never writes your password to disk.
When Beadbox restarts, the password is lost. To avoid re-entering it on every launch, set BEADS_DOLT_PASSWORD in your shell profile (see Persisting the Password).
Under the hood, Beadbox passes the password to the bd CLI via the BEADS_DOLT_PASSWORD environment variable on each subprocess invocation.

Hosted Dolt and Remote Servers

For Dolt servers running on a remote machine, a cloud VM, or Hosted Dolt:

Host: Enter the hostname or IP of your server.
Port: Use the port your provider specifies. Hosted Dolt typically uses 3306.
User/Password: Enter the credentials from your provider.
TLS: Check "Use TLS" (required for Hosted Dolt and recommended for any remote connection).
Click Discover Databases and proceed normally.

Persisting the Password

Beadbox holds passwords in memory only, so they are lost on restart. For any server that requires authentication (local or remote), you can skip re-entering the password by setting it in your shell profile:

export BEADS_DOLT_PASSWORD="your-password-here"

Beadbox picks this up automatically for all server-mode workspaces. The UI password field takes precedence if both are set.

How It Works

When you add a server workspace, Beadbox does three things:

1. Writes connection metadata

It creates a .beads/metadata.json in the local project directory with the server connection details:

{
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 3307,
  "dolt_database": "beads_myproject",
  "dolt_server_user": "root",
  "database": "dolt"
}

When TLS is enabled, a "dolt_server_tls": true key is added. This file tells bd to connect to a remote server instead of using a local embedded database. The password is intentionally absent from this file.

2. Registers the workspace

The local directory is added to ~/.beads/registry.json so Beadbox and bd can find it on future launches.

3. Passes credentials at runtime

Every time Beadbox invokes a bd command for this workspace, it sets BEADS_DOLT_PASSWORD in the subprocess environment. The password lives in process memory only.

Troubleshooting

Connection refused

Error: connect ECONNREFUSED 127.0.0.1:3307

Is Dolt running? Check with ps aux | grep dolt or try dolt sql-server in the project directory.
Right port? Dolt defaults to 3307, but you may have configured a different port.
Firewall? On remote servers, make sure the port is open for inbound connections.

Access denied

Error: Access denied for user 'root'

Password required? Your Dolt server may have authentication enabled. Enter the password in the connection form.
Wrong user? Verify the username matches a Dolt user with read access.
Wrong password? Passwords are not saved between sessions. Re-enter it after restarting Beadbox.

TLS handshake failure

Error: TLS handshake failed

TLS checkbox mismatch. If the server requires TLS, check "Use TLS." If it doesn't support TLS, uncheck it. Having this wrong in either direction causes a handshake failure.
Self-signed certificates. If your Dolt server uses a self-signed certificate, you may need to add the CA to your system trust store. The bd CLI uses the system root CA pool and will reject untrusted certificates.

No databases found

No beads databases found on 127.0.0.1:3307.
Databases must follow the beads_* naming pattern.

Naming convention. Beadbox only discovers databases whose names start with beads_. If your database is named something else, rename it or create a new one with bd init using Dolt mode.
Database exists but not visible? The user account may not have permission to see all databases.
Fresh server? If you just started Dolt without initializing beads, there are no beads databases yet. Run bd init in a project directory with Dolt mode configured, then retry discovery.