Skip to content
Skills Library
Programming · Testing

bifrost-debug

/bifrost-debug

Boot an isolated, hot-reload Bifrost dev stack for the current worktree via ./debug.sh. Use when the user wants to click around the UI, view a feature in the browser, screenshot something, or otherwise needs the dev stack running. Per-worktree isolation lets multiple worktrees run dev stacks in parallel. Trigger phrases - "open the app", "let me click around", "spin up debug", "test in the browser", "show me the UI", "/bifrost-debug".

Repository
bifrost ↗
Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Boot an isolated, hot-reload Bifrost dev stack for the current worktree via ./debug.sh. Use when the user wants to click around the UI, view a feature in the browser, screenshot something, or otherwise needs the dev stack running. Per-worktree isolation lets multiple worktrees run dev stacks in parallel. Trigger phrases - "open the app", "let me click around", "spin up debug", "test in the browser", "show me the UI", "/bifrost-debug".

Triggers from the description

open the applet me click aroundspin up debugtest in the browsershow me the UI
Original author description

Boot an isolated, hot-reload Bifrost dev stack for the current worktree via ./debug.sh. Use when the user wants to click around the UI, view a feature in the browser, screenshot something, or otherwise needs the dev stack running. Per-worktree isolation lets multiple worktrees run dev stacks in parallel. Trigger phrases - "open the app", "let me click around", "spin up debug", "test in the browser", "show me the UI", "/bifrost-debug".

How it works

  1. When to activate
  2. Two boot modes (auto-detected)
  3. The basic flow
  4. Connect the CLI
  5. Lifecycle: who tears down what
  6. Hot reload — don't restart for code changes
  7. Multi-worktree
  8. Common failures
  9. What this skill does NOT do
Original SKILL.md headings · 151 lines, 1,292 words
SKILL.md preview
---
name: bifrost-debug
description: Boot an isolated, hot-reload Bifrost dev stack for the current worktree via ./debug.sh. Use when the user wants to click around the UI, view a feature in the browser, screenshot something, or otherwise needs the dev stack running. Per-worktree isolation lets multiple worktrees run dev stacks in parallel. Trigger phrases - "open the app", "let me click around", "spin up debug", "test in the browser", "show me the UI", "/bifrost-debug".
---

# Bifrost Debug

Bring up a per-worktree, hot-reload Bifrost dev stack via `./debug.sh`. Hand the user the URL. Don't restart containers for code changes (hot reload handles it).

## When to activate

- User wants to click around the UI: "open the app", "let me try this in the browser", "show me the form", "I want to test this".
- User wants screenshots of a feature.
- User explicitly invokes `/bifrost-debug`.
- Before manually verifying a UI change at the end of a feature (per `bifrost-testing` Definition of Done).

Do **not** activate for backend-only work that can be verified via tests, type generation, or `curl` against a running stack.

## Two boot modes (auto-detected)

`./debug.sh` picks the mode based on whether `NETBIRD_SETUP_KEY` is available in the env (process env, or `~/.config/bifrost/debug.env`):

- **Mode A — netbird:** key present. The peer joins the private NetBird mesh and creates an ephemeral public HTTPS URL with `netbird expose`. No host ports, durable Admin proxy mappings, or NetBird API key are required. `./debug.sh status` reports both URLs.
- **Mode B — port:** no key. Client exposed on a deterministic free host port (30000–39999, hashed from worktree path). Reachable at `http://localhost:<port>`. Default for most local development.

The user picks the mode by setting (or not setting) `NETBIRD_SETUP_KEY` in `~/.config/bifrost/debug.env`. Don't try to switch modes for them.

Mode A stores a strong generated admin password per worktree under the user's local state directory and reports it from `./debug.sh status`. Never replace it with the shared `password` development credential while public exposure is active.

**Optional in Mode A:** `NETBIRD_EXTRA_DNS_LABELS` in `~/.config/bifrost/debug.env` adds private-mesh DNS aliases for the peer (comma-separated, e.g. `bifrost,debug-current` → `bifrost.netbird.cloud`, `debug-current.netbird.cloud`). Wildcards work (`*.myserver`). Don't set this for the user — they manage it themselves.

## The basic flow

1. **Check status first.** Don't re-boot if already up.

   ```bash
   ./debug.sh status
   ```

   If the output shows `Status:   UP`, parse the `Open:` line and hand the URL straight to the user. Stop.

2. **If down, boot it (backgrounded).** `./debug.sh up` runs `docker compose up -d --build` and then waits up to 180s for the API health check. First boot can take 1-3 minutes for the image build, so use a background shell:

   ```bash
   # Bash(run_in_background=true)
   ./debug.sh up
   ```

   Tail the background output with BashOutput until you see one of:
   - `Open:     http://...` — success. Hand the URL to the user.
   - `ERROR: api did not become ready` — failure. Run `./debug.sh logs api` and report what's wrong.

3. **Tell the user the credentials.** Login is `dev@gobifrost.com` / `password`. MFA is off. No setup wizard. Mention this once with the URL.

4. **Point at logs if they ask.** `./debug.sh logs <service>` — services include `api`, `client`, `worker`, `scheduler`, `postgres`, `redis`, `seaweedfs`.

## Connect the CLI

Bifrost can keep credentials for several instances. Only `.env` in the exact
invocation directory selects the URL for commands run there; ancestor dotenv
files are never discovered implicitly. Credentials remain in the global store
keyed by URL. Otherwise the CLI uses the user's saved default. Debug should use
its own scratch-directory selector and must not change that saved default.

After the stack is up, create one scratch directory for this worktree. Never
run debug CLI commands from bare `/tmp`.

```bash
mkdir -p /tmp/bifrost-cli-<worktree-name>
cd /tmp/bifrost-cli-<worktree-name>
touch .env
python3 -m venv .venv
./.venv/bin/pip install --quiet --upgrade pip
./.venv/bin/pip install --quiet "<URL_FROM_DEBUG_STATUS>/api/cli/download"
./.venv/bin/bifrost login --url <URL_FROM_DEBUG_STATUS> \
  --email dev@gobifrost.com --password password
```

The scratch directory's own `.env` is the only local selector the CLI reads;
ancestor dotenv files are ignored. Login writes only this debug stack's URL
there and stores its credentials globally under that URL. Run all later
debug-instance CLI commands from the same scratch directory with
`./.venv/bin/bifrost ...`.

Run `./debug.sh` commands from the worktree, never from the scratch directory.
If the connection is ever unclear, `bifrost auth default` is a read-only check:
the `Current connection` line is what commands in that folder will use.

When explicitly tearing down the stack, clear its folder binding before or
after `./debug.sh down`:

```bash
cd /tmp/bifrost-cli-<worktree-name>
./.venv/bin/bifrost logout --url <URL_FROM_DEBUG_STATUS> --yes
```

## Lifecycle: who tears down what

- **The stack outlives this Claude session.** Closing or clearing the session does NOT tear it down. This is intentional — the user might come back, or have another Claude session attach to the same stack.
- To tear down explicitly: `./debug.sh down`. This removes containers and volumes (postgres data is lost — fine for a debug stack; not fine for the prod stack).
- If the user says "stop the debug stack" or "wipe the debug data," run `./debug.sh down`.
- If a second Claude session or a new conversation comes up while the stack is already running, that's fine — `./debug.sh status` will reveal it. Don't call `./debug.sh up` redundantly; just hand over the URL from `status`.

## Hot reload — don't restart for code changes

Same rule as the dev stack always had:

- API, scheduler, worker: `watchmedo` / uvicorn `--reload` watches `/app/src` and `/app/shared`. Saves cause an automatic restart.
- Client: Vite HMR. Browser updates instantly.

**Never** run `docker compose restart api` (or any service) just because you edited Python. Restart only when:
- New Python dependency in `pyproject.toml` (then rebuild: `docker compose -f docker-compose.debug.yml up -d --build api`).
- New alembic migration (then `docker compose -f docker-compose.debug.yml restart init` to apply, then `restart api`).

Set the user's expectation: "your edit will be live in a few seconds, no restart."

## Multi-worktree

Two worktrees can run debug stacks in parallel. They get different Compose project names (`bifrost-debug-<hash>`), separate volumes, separate ports. To list all running debug stacks:

```bash
docker ps --filter "name=bifrost-debug-" --format "{{.Names}}"
```

Group by project name to find each worktree's URL: `cd <worktree> && ./debug.sh status`.

## Common failures

**API won't come up:**
- `./debug.sh logs init` — migrations failing? Compare `git log origin/main -- api/alembic/versions/` against the worktree.
- `./debug.sh logs api` — usually a config / import error. The traceback is usually in the first 30 lines of output after the start banner.

**Login still shows the setup wizard:**
- The seed-user provisioning runs on every API boot. If the wizard appears, the seed env vars probably aren't loaded — check `docker compose -f docker-compose.debug.yml exec api env | grep BIFROST_DEFAULT_USER`. If empty, `.env.debug` isn't being sourced; investigate `load_env_files` in `debug.sh`.
- "User already exists" on the wizard: a previous (broken) seed user lingers without an org. Run `./debug.sh down` (wipes the DB volume) and `./debug.sh up` again.

**Mode A can't be reached at the public URL:**
- Run `./debug.sh status`. If it only shows the private URL, inspect `./debug.sh logs netbird` for Peer Expose permissions or certificate provisioning errors.
- Confirm Peer Expose is enabled for the setup key's peer group under NetBird **Settings → Clients**.
- The public service is ephemeral. Restarting the NetBird container issues a new URL; `debug.sh` applies it to `BIFROST_PUBLIC_URL` automatically.

**Mode A can't be reached at the private hostname:**
- DNS propagation in Netbird takes a few seconds after first peer enrollment. Wait 30s and retry.
- Confirm the peer is registered: `docker compose -f docker-compose.debug.yml logs netbird | tail -20`. Look for `Peer registration completed`.

**Mode B port not reachable:**
- `./debug.sh status` re-reads the published port from `docker port`. If `Open:` shows nothing, the client container didn't start — `./debug.sh logs client`.

## What this skill does NOT do

- Doesn't manage NetBird account settings. Peer Expose must already be enabled for the debug peer group.
- Doesn't set up `~/.config/bifrost/debug.env` — point the user at it, don't write keys there for them.
- Doesn't run tests. That's the `bifrost-testing` skill's job.
- Doesn't reset DB state. `./debug.sh down` wipes the volume; there's no fast in-place reset (unlike `./test.sh stack reset`).

Versions

RepositoryScoreLicence
This page · gobifrost/bifrost100AGPL-3.0
gobifrost/bifrost100AGPL-3.0

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 105fbd456304 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bifrost-testing
    Run and write tests for Bifrost. Use when writing or running tests; adding or modifying React components, pages, or user-facing features; debugging failing or flaky tests; before declaring UI or backend work complete. Trigger phrases - "write a test", "run tests", "add a…
  • 100worktree
    Creates git worktrees for isolated development. Use when user wants to "create a worktree", "start a new feature branch", "work on a fix in isolation", or needs a parallel development environment.
  • 93setup
    Set up Bifrost SDK - install CLI, authenticate, configure MCP server. Use when user needs to get started with Bifrost or has incomplete setup.
  • 95dev_manage_git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch…
  • 100parallel-branches
    Runs several git branches side by side, each in its own worktree with its own dev server and port, so they can be compared in the browser. Use when the user wants to work on multiple tasks or branches at once, run different branches at the same time, check two branches in a…
  • 100parallel-worktrees
    Run multiple AI coding agent sessions in parallel using git worktrees — each agent isolated in its own worktree, working on a separate branch. Use this skill whenever the user wants to: run two or more AI agents simultaneously on different features or bugs, set up isolated agent…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.