How to Configure Beads Server Mode for External Dolt Connections

Set the BEADS_DOLT_SERVER_MODE=1 environment variable or run bd init --server to force Beads into External mode, where it connects to an existing Dolt sql-server rather than spawning its own.

The gastownhall/beads repository supports three Dolt operating modes, with External (server) mode allowing you to manage the Dolt sql-server lifecycle independently via Docker, systemd, or managed services. This configuration prevents Beads from auto-spawning database processes and instead relies on a persistent TCP connection to an externally managed Dolt instance.

How Beads Determines the Server Mode

The resolution logic is centralized in internal/doltserver/servermode.go within the ResolveServerMode function (lines 48-52). Beads evaluates configuration sources in the following strict precedence:

1. BEADS_DOLT_SERVER_MODE=1 environment variable → External mode.
2. BEADS_DOLT_SHARED_SERVER environment variable or shared_server: true in config.yaml → External mode.
3. metadata.json with "dolt_mode":"embedded" → Embedded mode.
4. metadata.json with explicit dolt_server_port → External mode.
5. Default → Owned mode (Beads manages the server lifecycle automatically).

When the evaluation resolves to External mode, Beads attempts TCP connections to 127.0.0.1 on the configured port and never executes dolt sql-server itself.

Configuration Methods

You can enable External mode through environment variables, CLI flags, or project metadata files.

Environment Variable Method

Export BEADS_DOLT_SERVER_MODE=1 in your shell. This takes highest precedence in the resolution logic and forces External mode without modifying project files.

export BEADS_DOLT_SERVER_MODE=1
bd init
bd doctor --server

Project Initialization Flag

Running bd init --server creates a .beads/metadata.json file containing "dolt_server_port": 3307. According to cmd/bd/init.go (lines 152-153), this flag persists the server configuration while internally treating the project as External mode.

bd init --server

Shared Server Configuration

Set BEADS_DOLT_SHARED_SERVER or add shared_server: true to config.yaml. This alternative environment variable triggers the same External mode resolution in internal/doltserver/servermode.go.

Manual metadata.json Configuration

For custom ports or remote hosts, edit .beads/metadata.json. The DoltServerPort field is defined in internal/configfile/configfile.go (line 30); its presence forces External mode regardless of environment variables.

{
  "backend": "dolt",
  "database": "dolt",
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 3400
}

Connecting to an External Dolt Server

In External mode, Beads requires a running Dolt sql-server before executing any database commands (e.g., bd sync, bd list).

Docker Example

Start an external Dolt container:

docker run -d --name dolt \
  -p 3307:3307 \
  ghcr.io/dolthub/dolt:latest \
  dolt sql-server --host 0.0.0.0 --port 3307

Then configure Beads to connect:

export BEADS_DOLT_SERVER_MODE=1
bd init --server
bd doctor --server

The bd doctor --server command executes server-specific health checks documented in docs/DOLT.md (line 312) to verify TCP connectivity and authentication.

Switching from Owned to External Mode

bd dolt stop                    # Stop the auto-spawned server

export BEADS_DOLT_SERVER_MODE=1 # Or run bd init --server

bd doctor --server              # Verify external connectivity

Reverting to Owned Mode

unset BEADS_DOLT_SERVER_MODE
rm .beads/metadata.json    # Or remove the dolt_server_port field

bd dolt start              # Beads resumes auto-spawning

Use Cases for External Server Mode

Multi-writer workloads – Multiple Beads processes or external tools can safely read and write the same Dolt database without file-level lock contention inherent in Embedded mode.

Process isolation – Manage the Dolt server lifecycle independently using systemd, Kubernetes, or Docker, providing independent restarts, resource limits, and logging.

Performance optimization – Running Dolt as a separate process allows better CPU core utilization for concurrent transactions compared to the in-process Embedded library.

Summary

• External mode forces Beads to connect to an existing Dolt sql-server rather than auto-spawning one.
• Configuration follows strict precedence defined in internal/doltserver/servermode.go: environment variables override metadata.json settings.
• Use BEADS_DOLT_SERVER_MODE=1, BEADS_DOLT_SHARED_SERVER, or bd init --server to enable External mode.
• The external server must run on 127.0.0.1:3307 by default, configurable via dolt_server_port in metadata.json.
• Validate connectivity using bd doctor --server before executing database commands.

Frequently Asked Questions

What is the default port for external Dolt connections in Beads?

Beads defaults to port 3307 when initializing with bd init --server. This value is written to metadata.json as dolt_server_port and defined in internal/configfile/configfile.go (line 30). You can customize this port if your external Dolt server listens on a different address.

How do I verify that Beads is successfully connecting to my external Dolt server?

Run bd doctor --server to execute server-specific health checks. This command, documented in docs/DOLT.md (line 312), verifies that Beads can establish a TCP connection to the host and port specified in your configuration and reports any authentication or connectivity errors.

Can I use External mode with a remote Dolt server not running on localhost?

Yes. While Beads defaults to 127.0.0.1, you can specify a different host by editing .beads/metadata.json and adding the dolt_server_host field with your remote IP address or hostname. Ensure the dolt_server_port field is also set, as its presence triggers External mode resolution.

What happens if I enable External mode but the Dolt server is not running?

Beads commands that require database access (such as bd sync or bd list) will fail with connection errors. Unlike Owned mode, External mode does not auto-spawn a server; the external process must be running before you invoke Beads commands, as implemented in the connection logic throughout the codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}