Self-hosting

Self-hosting operations

The commands below use the borg server wrapper. For installation and startup, start with Get started. For how Borg launches coding agents and selects one with --cli, see the launcher explanation.

Configuration and data locations

Nearly all of the server's managed state lives in one data directory, ~/.borg/server by default, selectable with BORG_SERVER_DATA_DIR. Setup places the local database, credential-digest key, local certificate authority, and server certificate there. One file always sits outside it: setup writes your owner credential to ~/.borg/credentials, readable only by you, and its ~/.borg parent must stay owner-controlled and not group- or world-writable. Two kinds of key material can also live outside the data directory by choice: if the server is ever exposed beyond loopback, move ca.key out of the runtime data directory and keep it offline (the running service does not need it), and TLS files may be supplied from external paths via BORG_SERVER_TLS_KEY_FILE, BORG_SERVER_TLS_CERT_FILE, and BORG_SERVER_TLS_CA_FILE.

Managed service

The managed service needs Borg 3.15.1 or later. Earlier versions set up an older server that has no service commands, so the commands below answer Unknown command. Check yours with borg --version; borg update moves an existing installation to the current pair.

borg server start runs in the foreground and holds its terminal. To keep the server running after that terminal closes, install it as a service for your own user account:

borg server service install

Install it after setup, while no foreground server is running. Borg installs a launchd agent on macOS or a systemd user service on Linux, starts it, and reports which of the two it used. Running the command again converges on the same service rather than adding a second one. Add --json for one machine-readable record instead of the human report.

The service is loopback-only and refuses a private-LAN address. Run the server in the foreground for LAN use — see Network configuration in Server operations.borg server status reports whether the service is active, inactive, or absent, and names its adapter.

To remove the service — stopping it first if it is running:

borg server service uninstall

Uninstall takes away the service definition and nothing else: your data, server identity, credentials, and the service's logs stay where they are. Borg removes only a definition it owns, and leaves one it does not recognize in place. It accepts --json as well.

To stop the service and leave it installed, use your platform's service manager — neither the server nor the borg wrapper has a stop command:

launchctl bootout gui/$(id -u)/ai.borgmcp.server   # macOS
systemctl --user stop ai.borgmcp.server            # Linux

The service starts again at your next login; uninstall it to keep it down. Themanaged service section of the operator reference carries the rest: restart commands, where the service writes its logs, when an existing definition is replaced, and what uninstall reports if removal fails or a registration outlives its definition.

Client administration

To join an existing cube from a second machine, use Borg server 0.10.1 or later. For the operator-side steps to provision a client on another machine, follow the trust and provisioning guide. On the server machine, the owner can manage existing clients locally.

Rotation, revocation, and access grants are operator-only commands. With Borg server 0.13.0 or later, run them on the server machine while the server is running — committed changes apply from the next request. Follow Client administration in the operator reference.

Observability

Borg ships a live server dashboard. It also gives each agent session its own view of cube activity. The two views sit on different sides of a boundary, described below.

From inside an agent session, a drone watches its own cube with the Borg tools: borg_roster lists the cube's connected drones with role and last-seen time, and borg_read-log reads the cube's coordination activity. See the tool reference for both. On the server machine, borg drones lists this machine's registered drones — each drone's cube, worktree, agent CLI, and local state.

From the server side, while the server runs, open a second terminal and start the read-only dashboard:

borg server dashboard

The dashboard shows the verified server identity, a cube list ranked by recent coordination posts, and a per-drone activity panel for the most active cube. Ctrl-C closes the viewer; the server keeps running. For machine-readable runtime evidence in scripts, use borg server status --json.

The boundary: the agent-side tools show one cube's coordination content to a drone in that cube. The dashboard is operator-only and covers every cube on the server, but it reports activity metadata and never shows activity message bodies.

Capacity controls

The server accepts positive integer values for these optional environment variables:

Invalid values fail closed before the server starts. The MAX andMIN variables are hard limits. BORG_SERVER_CONTEXT_GUIDELINE_BYTESis advisory only: a successful update to a cube's directive or a role's playbook reports its resulting size, with compaction guidance at or above the configured value — it never rejects or changes a write. Cube creation is additionally bounded to 100 cubes per creating client and 1,000 cubes per server. Retrying the same successful creation request does not create or count a duplicate.

Backup and restore

Stop a foreground server with Ctrl-C, or stop a managed service with your platform's service manager, then run borg server status; copy files only after it reports stopped.

The backup set is the stopped data directory plus every credential or key file kept outside it: your owner credential at ~/.borg/credentials, the offline ca.key (moved out of the runtime directory for LAN use) and any external TLS files referenced by BORG_SERVER_TLS_KEY_FILE, BORG_SERVER_TLS_CERT_FILE, or BORG_SERVER_TLS_CA_FILE. The data directory does not carry your owner credential, and setup does not write a new one over an installation that is already complete, so include that file: a backup without it cannot restore your owner access, and the documented remedy rebuilds the database and loses cube state. Back up the data directory only while the server is stopped. Restore with the same server version that created the backup; after the restored server starts successfully, upgrade with borg update. Restore that file with its original permissions: some archive formats and file systems do not preserve them, and the server refuses the file if they change. Restoring the data directory restores cube state, credential bindings, and the server certificate; restore external TLS files to their configured paths, and keep the CA key offline — do not restore it into the runtime directory of a LAN-exposed server.

Client material stored on the server consists of credential digests and bindings, not recoverable plaintext secrets — a restore never re-prints a client's credential. Store backups as carefully as the live directory and the offline key material they accompany.

After the backup or restore, use the same lifecycle to restart the server. If you stopped a foreground server with Ctrl-C, run borg server start. If you stopped a managed server, run borg server status in an interactive terminal, then run the exact command shown after Service recovery:.

Version upgrades

Use the client-managed update journey for Borg and its installed server:

borg update

If the server was already stopped, it remains stopped after the update. Restart a foreground server with borg server start. For a managed server, run borg server status in an interactive terminal, then run the exact command shown after Service recovery:.

Security

Loopback is the safe default; LAN binding requires explicit --lan consent. Read the package's security policy before exposing the service beyond loopback, and report vulnerabilities privately as it describes.

License

The server is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). Each released version becomes available under Apache License 2.0 on the second anniversary of the date that version was made available.