How to Troubleshoot SwarmForge Dashboard Connection Issues: A Complete Guide

SwarmForge dashboard connection issues typically stem from the dashboard-url file not being created, a port conflict on the default 64002 port, or a crashed HTTP server—verify the file exists, check dashboard.log, and clear stale .swarmforge state to resolve.

The SwarmForge dashboard is a lightweight web UI that starts automatically when you run the host (./swarm or bb swarmforge.bb). Understanding how the host communicates with this dashboard—and where that communication can break down—is essential for quickly diagnosing problems. This guide walks through the exact mechanisms in unclebob/swarm-forge and provides practical fixes based on the source code.

How the SwarmForge Dashboard Connection Works

The connection between host and dashboard relies on three core components working in sequence.

Core Components

Component	Source File	Primary Function
Web server launcher	swarmforge/scripts/pack_web.bb	Starts HTTP server, writes reachable URL to disk
Host orchestrator	swarmforge/scripts/swarmforge.bb	Waits for URL file, prints it to console
Dashboard UI	swarmforge/scripts/pack/dashboard.html	Static UI that calls backend APIs on same port

Connection Sequence

1. Host invokes pack_web.bb — when you start ./swarm, the host script launches the web server
2. Server binds to local port — default 64002 on 127.0.0.1, stored in dashboard-port variable
3. URL persistence — write-dashboard-url! creates <state-dir>/.swarmforge/dashboard-url containing the URL
4. Host reads and displays URL — swarmforge.bb uses wait-for-file (5-second timeout) to read the URL and print it

If the dashboard-url file never appears, the host aborts with: "No visible Terminal surfaces; use the dashboard."

Common Failure Modes and Diagnosis

No URL Printed, Host Appears to Stall

Root cause: pack_web.bb never successfully writes the dashboard-url file.

Verify:

ls .swarmforge/dashboard-url

If missing, the web server failed to start. Check the runtime log:

tail -n 30 .swarmforge/dashboard.log

Dashboard Loads But Stays Blank

Root cause: Server started on a different port than recorded, or the browser cannot reach the reported port.

Verify: Open the exact URL printed by the host, then compare with the port in dashboard.log. Check for port mismatches.

Stale URL After Previous Crash

Root cause: Old dashboard-url file from a prior run; new server may fail due to port already in use.

Fix: Remove the stale file and restart:

rm .swarmforge/dashboard-url
./swarm

"Connection Refused" in Browser

Root cause: HTTP server process died (crash, OOM, missing Java runtime for the underlying HTTP kit).

Verify: Examine dashboard.log for stack traces. The server logs startup confirmation or fatal errors here.

Port Conflict on Default 64002

Root cause: Another process occupies the default port.

Verify and fix:

lsof -i :64002

# or

netstat -tlnp | grep 64002

Override the port via environment variable (read by pack_web.bb via System/getenv):

export SWARMFORGE_DASHBOARD_PORT=65000
./swarm

Step-by-Step Troubleshooting Checklist

Follow this ordered sequence to isolate the problem.

1. Confirm the Dashboard URL File Exists

cat .swarmforge/dashboard-url

Expected output: http://127.0.0.1:64002 (or your custom port)

2. Inspect the Dashboard Server Log

tail -n 30 .swarmforge/dashboard.log

Look for:

• Server started on http://... — confirmation of successful launch
• Any exception stack traces — indicates startup failure

3. Validate the Server Is Actually Listening

lsof -iTCP -sTCP:LISTEN -P | grep $(cat .swarmforge/dashboard-url | awk -F: '{print $3}')

No output means the server process exited or never started.

4. Force a Clean State Reset

rm -rf .swarmforge
./swarm

This removes old URLs, logs, and pending request queues.

5. Override the Default Port

export SWARMFORGE_DASHBOARD_PORT=65500
./swarm

pack_web.bb uses this value when calling run-server if present.

6. Run the Automated Test Suite

The repository includes Playwright integration tests that validate the full startup flow:

cd test/dashboard
npm install
npx playwright test

Failures here indicate server-side problems or missing dependencies.

Advanced Diagnostic Techniques

Manually Start the Dashboard Server

Bypass the ./swarm wrapper to isolate server issues:

cd /path/to/swarm-forge
bb swarmforge/scripts/pack_web.bb

Direct output shows the actual bind address and any immediate crashes.

Inspect Pending API Requests

When the UI loads but shows "no tasks," check for unconsumed requests:

ls .swarmforge/dashboard/requests/pending
cat .swarmforge/dashboard/requests/pending/<request-id>.request

These JSON blobs are created by pack_dashboard_request.bb and fetched by the UI via GET /api/chat or POST /api/ui endpoints.

Review the Host Orchestrator Logic

In swarmforge.bb, the key function is wait-for-file on the dashboard-url path. If this times out after 5 seconds, the host aborts. Understanding this timeout helps distinguish between slow startup vs. complete failure.

Key Source Files Reference

File Path	Purpose	Relevant Functions/Variables
swarmforge/scripts/pack_web.bb	HTTP server lifecycle	dashboard-port, write-dashboard-url!, run-server
swarmforge/scripts/swarmforge.bb	Host dashboard coordination	wait-for-file, URL printing logic
swarmforge/scripts/pack_dashboard_request.bb	API endpoints for UI	/api/chat, /api/ui handlers
swarmforge/scripts/pack/dashboard.html	Static dashboard interface	Frontend JavaScript calling backend
test/dashboard/dashboard.spec.js	Integration validation	Playwright startup tests
.swarmforge/dashboard.log (runtime)	Server stdout/stderr	Startup confirmation, crash traces
.swarmforge/dashboard-url (runtime)	IPC between host and UI	Single-line URL file

Summary

• The dashboard-url file is the linchpin — if missing, the web server in pack_web.bb never completed startup
• Check .swarmforge/dashboard.log first for server-side error messages
• Port conflicts on 64002 are common; use SWARMFORGE_DASHBOARD_PORT to relocate
• Stale state from crashed runs causes misleading failures; rm -rf .swarmforge provides clean slate
• Playwright tests in test/dashboard/ offer automated validation of the full pipeline

Frequently Asked Questions

Why does SwarmForge say "No visible Terminal surfaces; use the dashboard"?

The host in swarmforge.bb timed out waiting for the dashboard-url file. This means pack_web.bb failed to start the HTTP server or write the file. Check dashboard.log for the underlying error and verify no port conflict exists.

Can I run the dashboard on a different port?

Yes. Set the SWARMFORGE_DASHBOARD_PORT environment variable before starting. The pack_web.bb script reads this via System/getenv and passes it to run-server instead of the default 64002.

Where are dashboard errors logged?

Runtime server output goes to .swarmforge/dashboard.log in your working directory. This includes successful startup messages, port binding confirmation, and any stack traces from crashes.

What if the dashboard URL file exists but the browser cannot connect?

The server likely crashed after writing the file, or a firewall blocks the loopback port. Verify with lsof that a process is still listening on the reported port, then check dashboard.log for exit reasons.

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