# How to Configure Beads Server Mode for External Dolt Connections

> Configure Beads server mode for external Dolt connections by setting BEADS_DOLT_SERVER_MODE=1 or running bd init --server. Connect to an existing Dolt sql-server easily.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: how-to-guide
- Published: 2026-04-27

---

**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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/config.yaml) → **External** mode.
3. **[`metadata.json`](https://github.com/gastownhall/beads/blob/main/metadata.json)** with `"dolt_mode":"embedded"` → **Embedded** mode.
4. **[`metadata.json`](https://github.com/gastownhall/beads/blob/main/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.

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

```

### Project Initialization Flag

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

```bash
bd init --server

```

### Shared Server Configuration

Set `BEADS_DOLT_SHARED_SERVER` or add `shared_server: true` to [`config.yaml`](https://github.com/gastownhall/beads/blob/main/config.yaml). This alternative environment variable triggers the same External mode resolution in [`internal/doltserver/servermode.go`](https://github.com/gastownhall/beads/blob/main/internal/doltserver/servermode.go).

### Manual metadata.json Configuration

For custom ports or remote hosts, edit [`.beads/metadata.json`](https://github.com/gastownhall/beads/blob/main/.beads/metadata.json). The `DoltServerPort` field is defined in [`internal/configfile/configfile.go`](https://github.com/gastownhall/beads/blob/main/internal/configfile/configfile.go) (line 30); its presence forces External mode regardless of environment variables.

```json
{
  "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:

```bash
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:

```bash
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`](https://github.com/gastownhall/beads/blob/main/docs/DOLT.md) (line 312) to verify TCP connectivity and authentication.

### Switching from Owned to External Mode

```bash
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

```bash
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`](https://github.com/gastownhall/beads/blob/main/internal/doltserver/servermode.go): environment variables override [`metadata.json`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/metadata.json) as `dolt_server_port` and defined in [`internal/configfile/configfile.go`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/.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.