# How to Access the SwarmForge Pack Cockpit Dashboard: Complete Guide

> Learn how to access the SwarmForge Pack Cockpit dashboard. Find the URL in .swarmforge/dashboard-url after running ./swarm for easy access.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The SwarmForge Pack Cockpit dashboard starts automatically when you run `./swarm` and serves on a dynamic localhost port, with the URL written to `.swarmforge/dashboard-url` for manual access.**

The **Pack Cockpit** is a local web dashboard that the host SwarmForge process launches automatically. According to the `unclebob/swarm-forge` source code, the dashboard is served by the `pack_web` component—a Babashka-based HTTP server that binds to `127.0.0.1` with a dynamically assigned port.

## Starting the Pack Cockpit Dashboard

### Automatic Launch with `./swarm`

The standard way to access the dashboard is through the main entry point in [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh)【4†L4-L6】:

```bash
./swarm

```

This wrapper script executes the Babashka host, which in turn runs `pack_web.bb` with the `--serve` command. The server starts on `127.0.0.1` with an available port【4†L66-L78】.

When initialization completes, two things happen:

1. The full URL is **printed to stdout** for copy-paste access【4†L74-L77】
2. The same URL is **written to `.swarmforge/dashboard-url`** for persistent reference【4†L58-L62】

By default, the URL also opens automatically in your default browser.

### Suppressing Automatic Browser Opening

For headless servers or when you prefer manual control, set the environment variable before running the host【4†L122-L123】:

```bash
SWARMFORGE_OPEN_BROWSER=0 ./swarm

```

The dashboard server still starts and the URL is written to `.swarmforge/dashboard-url`, but no browser window opens.

## Manual Dashboard Access Methods

### Reading the Stored URL

Once the host is running, retrieve the dashboard location at any time:

```bash
cat .swarmforge/dashboard-url

# Output: http://127.0.0.1:64002

```

### Opening the Dashboard Manually

Open the URL using your platform's command:

```bash

# macOS

open "$(cat .swarmforge/dashboard-url)"

# Linux

xdg-open "$(cat .swarmforge/dashboard-url)"

```

## Running the Pack Web Server Directly

For advanced use cases, you can invoke the server component directly via [`pack_web.sh`](https://github.com/unclebob/swarm-forge/blob/main/pack_web.sh) in `swarmforge/scripts/`【4†L4-L10】:

```bash
pack_web.sh --serve <root> [port]

```

Where `<root>` is the SwarmForge root directory (containing `.swarmforge`). The script dispatches to `pack_web.bb`, which:

- Parses the `--serve` argument
- Starts an `http-kit` server on the specified or dynamic port
- Blocks until terminated with **Ctrl-C**

## Key Source Files and Functions

| File | Purpose | Critical Lines |
|------|---------|--------------|
| [`swarmforge/scripts/swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/swarmforge.sh) | Host wrapper that launches the Babashka environment | Lines 4-6【4†L4-L6】 |
| `swarmforge/scripts/pack_web.bb` | Core dashboard server implementation | Server start: 66-78; URL writing: 58-62【4†L66-L78】【4†L58-L62】 |
| [`swarmforge/scripts/pack_web.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge/scripts/pack_web.sh) | Shell wrapper forwarding to Babashka script | Lines 4-10【4†L4-L10】 |
| [`README.md`](https://github.com/unclebob/swarm-forge/blob/main/README.md) | User documentation for dashboard access | Lines 103-112【4†L103-L112】 |
| `.swarmforge/dashboard-url` | Runtime file storing current dashboard URL | Generated by `write-dashboard-url!` function |

## Startup Flow Architecture

The dashboard initialization follows this execution path:

1. **User executes** `./swarm` in the project root
2. **[`swarmforge.sh`](https://github.com/unclebob/swarm-forge/blob/main/swarmforge.sh)** wrapper loads the Babashka environment
3. **Host process** starts `pack_web.bb` with `--serve` flag
4. **`pack_web.bb`**:
   - Parses command arguments
   - Starts HTTP server on dynamic localhost port
   - Calls `write-dashboard-url!` to persist the URL
   - Prints the URL to stdout
   - Optionally triggers browser opening (unless `SWARMFORGE_OPEN_BROWSER=0`)

## Summary

- The **Pack Cockpit dashboard** is a local web interface served by the `pack_web` component
- Access starts automatically with `./swarm`, with the URL stored in `.swarmforge/dashboard-url`
- Use `SWARMFORGE_OPEN_BROWSER=0` to disable automatic browser opening
- The core implementation lives in `swarmforge/scripts/pack_web.bb`, which handles server startup, URL persistence, and browser integration

## Frequently Asked Questions

### Where is the Pack Cockpit dashboard URL stored?

The URL is written to the hidden file `.swarmforge/dashboard-url` in your project root immediately after the server starts listening. This file is created by the `write-dashboard-url!` function in `pack_web.bb`【4†L58-L62】.

### Can I run the Pack Cockpit without starting the full host?

Yes. Run `pack_web.sh --serve <root> [port]` directly from `swarmforge/scripts/`. This launches only the dashboard server without the full SwarmForge host environment. The script forwards to `pack_web.bb` and blocks until you terminate it【4†L4-L10】.

### What port does the Pack Cockpit use?

The server binds to `127.0.0.1` with a **dynamically chosen available port** by default. You can specify a fixed port as the optional second argument to `pack_web.sh --serve <root> [port]`【4†L66-L78】.

### Why doesn't the browser open automatically on my server?

The auto-open feature is controlled by `SWARMFORGE_OPEN_BROWSER`. Set it to `0` to suppress opening, or if it's not opening on your system, check that the environment variable isn't already set to disable it. The dashboard URL is still printed and stored regardless【4†L122-L123】.