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.15.0+ 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.58.0+	`bd --version`
Dolt server	Running and accepting connections	`dolt sql-server` in your project
Beadbox	0.15.0+	Settings > About

Your Dolt server must have at least one database created by bd init. Beadbox discovers all user databases on the server (system databases like information_schema are excluded).

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
bd dolt start

bd starts Dolt on an OS-assigned port and stores it in .beads/dolt-server.port. The port is printed in the terminal output. If you run raw dolt sql-server instead, it defaults to 3307.

2. Open Beadbox

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

Tip: Alternatively, click Scan for servers to auto-detect running Dolt servers on localhost. If your server is found, Beadbox fills in the host and port for you.

3. Enter connection details

Host	`127.0.0.1` (pre-filled)
Port	Check your terminal output from bd dolt start, or look in .beads/dolt-server.port
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 user databases.

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"

If you have a local project directory with .beads/, Beadbox updates its metadata.json with the server connection details. If you are connecting to a remote server without a local project, Beadbox creates a stub workspace at ~/.beadbox/servers/ with its own metadata.json. Either way, the workspace is registered and opens immediately.

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 2-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. Set BEADS_DOLT_PASSWORD in your shell profile to avoid re-entering it on every launch (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 writes a .beads/metadata.json with the server connection details. For local projects, this file lives in the project directory. For server-only connections (no local project), it goes in ~/.beadbox/servers/.

{
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 13842,
  "dolt_database": "myproject",
  "dolt_server_user": "root",
  "database": "dolt"
}

When TLS is enabled, a "dolt_server_tls": true key is added. This file instructs bd to connect to the specified Dolt server rather than auto-starting a local one. The password is intentionally absent from this file.

2. Registers the workspace

The workspace is added to ~/.beadbox/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:<port>

Is Dolt running? Check with ps aux | grep dolt or try dolt sql-server in the project directory.
Right port? If you started Dolt via bd dolt start, the port is stored in .beads/dolt-server.port. Check that file for the current value. Raw dolt sql-server defaults to 3307.
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 databases found on 127.0.0.1:<port>.
Verify the Dolt server has at least one database created with bd init.

Naming convention. Verify that bd init has been run in at least one project directory. The database should appear in SHOW DATABASES on your Dolt server.
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, then retry discovery.