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".
- Author
- gobifrost ↗
- Repository
- bifrost ↗
- Licence
- AGPL-3.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
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
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
- When to activate
- Two boot modes (auto-detected)
- The basic flow
- Connect the CLI
- Lifecycle: who tears down what
- Hot reload — don't restart for code changes
- Multi-worktree
- Common failures
- What this skill does NOT do
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
| Repository | Score | Licence |
|---|---|---|
| This page · gobifrost/bifrost | 100 | AGPL-3.0 |
| gobifrost/bifrost | 100 | AGPL-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…