ZenUml/conf-app / .claude/skills/forge-tunnel
forge-tunnel
VerifiedRun a Forge tunnel to test local code changes on a live Confluence instance. Use when the user wants to test a Forge app locally, run forge tunnel, debug a Forge app on a live site, or verify manifest/config changes before deploying. Triggers on "forge tunnel", "tunnel to confluence", "test locally on confluence", "run tunnel", "test on diagramly", "test on lite-stg", or any request to proxy local Forge app code to a live Atlassian site.
Forge Tunnel
Run forge tunnel to proxy a live Confluence site to your local code. This lets you test manifest changes, new features, and bug fixes without deploying to staging/production.
Happy path (everything already configured)
pnpm build:lite # build the variant you care about
pnpm forge:deploy:dev # uploads dist/ + manifest to your dev env
pnpm forge:upgrade:dev # upgrades the install on your test site
FORGE_TUNNEL=1 PORT=8080 pnpm start:local:raw # vite on :8080 with the real bridge — leave running
# stop any existing Forge tunnel on this machine first
pnpm forge:tunnel # starts the tunnel — leave running (separate terminal)
Open the test site in a browser. Done.
If forge:upgrade:dev errors with "Could not find an installation", the app isn't installed yet — see First-time install below.
If forge:deploy:dev succeeds but forge:upgrade:dev errors with "scopes differ", just retry once — the deploy needs to settle.
Key constraints
-
Only one Forge tunnel may run for the same machine and Forge account. This is a hard preflight invariant. Before every
forge tunnelstart or restart, inspect the whole machine for an existingpnpm forge:tunnelparent and@forge/cli ... tunnelchild. If either exists, terminate that exact process tree first, wait for it to exit, and verify that no Forge tunnel process or tunnel listener remains. Never start a second tunnel alongside an existing one, even when the old tunnel points at the desired site/environment. Do not kill Vite, Wrangler, or unrelated development servers as part of this cleanup; they have separate ownership and lifecycle. -
Tunnel only works with DEVELOPMENT environments —
-e stagingand-e productionfail with "Cannot create tunnels outside of the development environment". -
The tunnel is identity-gated: it serves ONLY the browser logged in as the
FORGE_EMAILaccount (set in.env.forge.local;./scripts/forgex whoamiprints the account it resolves to). Any other identity silently receives the last-deployed CDN bundle — no error, no warning, no tunnel log line, while backend functions keep tunnelling normally for everyone. The default browser recipe inCLAUDE.md(agent-browser --session conf-app --restore=stg) restores the robot test account, so it CANNOT see tunnel code. Use a Chrome profile already logged in as theFORGE_EMAILaccount instead:agent-browser --session <name> --profile "Profile 8" <command>Chrome profile "Profile 8" (Conf App) carries that account; verify with
agent-browser --profile "Profile 8" open <site>/wiki/rest/api/user/currentand match itsaccountIdagainst./scripts/forgex whoami.agent-browser profileslists the others.--profilereuses existing login state; no credential entry is involved, andframe/evalinto the OOPIF keep working.Confirm it is actually working, in one check: inside the macro iframe,
location.hostmust belocalhost:8000(not…cdn.prod.atlassian-dev.net) and the scripts must be/@vite/client+/src/…, notassets/index-<hash>.js. From the shell,lsof -i :8080 | grep -c ESTABLISHEDmust rise above 0 when the macro loads. Measured 2026-08-21: the robot test account gave 0 connections and the hashed bundle; Profile 8 gave 8 connections and live Vite modules.Corollary: with the tunnel truly active the frontend is served from Vite source, so
pnpm build:liteis not needed for frontend edits — a page reload is enough. -
./scripts/forgexis the canonical entry point — it loads.env.forge+.env.forge.localand substitutes{{VAR}}placeholders. Allpnpm forge:*:devscripts use it. Don't callforgedirectly unless you're passing every env var inline. -
forge install(fresh, no--upgrade) requires a real TTY for the scope-confirmation prompt. Run with!so it executes in the user's terminal. -
forge deploypackages whatever is indist/— always build before deploy. -
The tunnel proxies to localhost:8080; it does NOT own that port. You must run
FORGE_TUNNEL=1 PORT=8080 pnpm start:local:rawseparately to put a Vite dev server there. Both variables are required:PORT=8080—pnpm start:localgoes through Portless and binds a random internal port, butmanifest.ymlhardcodestunnel.port: 8080, so the tunnel finds nothing.FORGE_TUNNEL=1— inservemodevite.config.mjsaliases@forge/bridgeto the Storybook stub (src/stubs/forge-bridge.ts) unless this is set. With the stub,view.getContext()returnsnull, the iframe loads Vite modules but#appstays empty and the macro height stays 0 — no error in the console. If port 8080 has a Vite process from another worktree (parent dir, sibling worktree, leftover from earlier session), the tunnel serves THAT worktree's code and you'll spend an hour debugging why your changes aren't showing up. See Stale Vite from another worktree.
-
adfExport(macro export) functions are NOT proxied by the tunnel. Atlassian's PDF/Word macro-export pipeline runs server-side independently of the user's session, even thoughaccountIdis attached to the payload. Empirically verified on 2026-05-16: aconsole.logprobe insrc/export.jsproduced ZERO log lines in the tunnel terminal when a PDF was exported from Confluence; the rendered PDF used deployed code, not local code. A control web trigger in the same tunnel session DID log immediately — so tunnel logging itself works fine. For any iteration onadfExportcode (src/export.jsin this repo),forge deploy -e developmentis required after each change —forge tunnelalone will not pick up your edits. Seedocs/superpowers/specs/2026-05-15-paywall-research-framing-corrections.md§B4 for the full test write-up. Tunnel still works as expected for Custom UI resolvers, web triggers, and frontend iframe assets — only macro-export functions are the exception.
Setup (one-time per worktree)
Each worktree has its own .env.forge symlink and .env.forge.local (both are gitignored, so they DO NOT exist in a fresh worktree). When using-git-worktrees creates a new worktree, redo these steps before running any pnpm forge:* script.
If you skip this, forgex can't substitute {{ATLASSIAN_SITE}} / {{FORGE_ENV}}, the placeholders pass through to forge as empty strings, forge then prompts for the missing site, and you get the misleading error Prompts can not be meaningfully rendered in non-TTY environments. Re-run with --verbose to see the real prompt and remember: that error usually means env files are missing, not that you need a TTY.
Quick path for a new worktree (when the parent dir already has a working setup):
ln -sf .env.forge.lite .env.forge
cp ../<parent-worktree>/.env.forge.local .
1. Set active variant
ln -sf .env.forge.lite .env.forge # or .env.forge.full / .env.forge.dia
2. Create personal env file
cp .env.forge.local.example .env.forge.local
Edit .env.forge.local:
FORGE_ENV=<your-dev-env-name>
ATLASSIAN_SITE=<your-test-site>.atlassian.net
To discover yours, run forge environments list (lists dev environments deployed for the app) and forge install list -e <env> (shows which sites have it installed). Pick a (env, site) pair where the env is deployed AND the site has it installed — or be prepared to fresh-install on a site where you have admin rights.
The env name often doesn't match the site name. A site called
lite-dev.atlassian.netmay have its install in envdevelopment(notlite-dev). When the user says "test on lite-dev", that's the site —forge install listis the source of truth for which env the install actually lives in. Don't guess; check.
Step-by-step
1. Build the variant
pnpm build:lite # or build:full, build:diagramly
forge deploy packages dist/ — if you skip this, you'll deploy stale assets.
2. Deploy to the dev environment
pnpm forge:deploy:dev
Run this whenever the manifest changed, or you're not sure. Code-only changes don't strictly need a redeploy (the tunnel serves local files), but the manifest must match what the install expects.
3. Install or upgrade on the Confluence site
Default path:
pnpm forge:upgrade:dev
First-time install
If upgrade errors "Could not find an installation", the app isn't on that site yet. Fresh install needs a TTY (no --non-interactive flag, no --upgrade):
! ./scripts/forgex install --site {{ATLASSIAN_SITE}} --product confluence -e {{FORGE_ENV}}
Use the
{{VAR}}template form, not$VAR. forgex substitutes{{VAR}}from.env.forge.localinternally;$VARis shell-expanded before forgex runs and is empty unless you've exported the var in your shell.
The ! runs it in the user's terminal. Forge will print the scope list and prompt for confirmation — press Enter/Y to accept.
4. Stop any existing Forge tunnel, then start the tunnel
Forge tunnel is machine/account singleton state. Inspect before starting:
pgrep -lf '(@forge/cli/.*/cli\.js tunnel|pnpm forge:tunnel)' || true
For every returned PID, inspect its command and working directory, then terminate only the confirmed Forge tunnel parent/child processes:
ps -p <pid> -o pid=,ppid=,etime=,command=
lsof -a -p <pid> -d cwd -Fn
kill -TERM <confirmed-forge-tunnel-pid> [...]
Wait for graceful exit and run the pgrep check again. Do not continue until it returns no Forge tunnel processes. If the tunnel belongs to a managed terminal/tool session, interrupt that session as well so it cannot respawn or retain stale ownership.
Then start the single replacement tunnel:
pnpm forge:tunnel
The tunnel is long-lived. If Claude is running it: use run_in_background: true and tail the output for Listening for requests on local port XXXXX.... If a human is running it: use a dedicated terminal tab and leave it open while testing.
To stop: Ctrl+C, or kill <pid> for a backgrounded one. No server-side cleanup needed.
5. Verify the tunnel is hitting your code
Open the test site in a browser. If this is a fresh install, you may need to insert a macro on a page first — go to a Confluence page → /zenuml, /mermaid, /graph, or /openapi → pick the macro. The macro then renders inside a Forge iframe served by your tunnel.
Once the macro renders:
- The tunnel terminal should print incoming proxied requests as the iframe loads. No requests = the tunnel isn't connected (wrong env, wrong site, or app not installed there —
forge install list -e <env>to verify). - If you don't see your code changes, hard-refresh (Cmd+Shift+R) — Confluence aggressively caches macro assets.
- If still stale, check that you're logged in as the same user the tunnel is associated with. The tunnel only intercepts YOUR authenticated session.
During development
Frontend changes (src/, dist/):
pnpm build:<variant> # rebuild
# tunnel auto-serves the new dist/ — no restart needed for asset changes
Backend changes (functions/): the tunnel auto-detects and reloads.
manifest.yml changes: full cycle — forge deploy + forge install --upgrade + tunnel restart.
Apps and env files
| App | APP_ID | .env.forge symlink target |
|---|---|---|
| Lite | 8ad26115-211f-4216-971b-0540f606303d | .env.forge.lite |
| Full | d9e4002b-120b-426b-834b-402a4a5adce7 | .env.forge.full |
| Diagramly | 01ede8b1-4e88-451a-b9ef-89eeef93afaf | .env.forge.dia |
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| "Cannot create tunnels outside of the development environment" | Using -e staging / -e production | Use a development env name |
| "The scopes or egress URLs differ from most recent deployment" | Manifest changed since last deploy to this env | Run pnpm forge:deploy:dev first |
"Could not find an installation" on --upgrade | App not installed on that site yet | Fresh install path (! ./scripts/forgex install ...) |
"Prompts can not be meaningfully rendered in non-TTY environments" on a fresh forge install (no --non-interactive) | Fresh install prompts for scope confirmation | Run with ! prefix in user's terminal |
| "Insufficient permissions to install app" | Forge CLI can't auto-consent in headless mode, OR your user isn't admin on that site | Use interactive ! install; if still fails, you need site-admin on that site (use a different env/site) |
| Tunnel listening but no incoming requests when you load the page | Wrong env, wrong site, or app not installed there | forge install list -e <env> to verify |
Tunnel returns 500 AggregateError / Failed to connect to localhost:8080 | No Vite dev server on :8080 — tunnel proxies but doesn't host | Run FORGE_TUNNEL=1 PORT=8080 pnpm start:local:raw in the same worktree |
Iframe is localhost:8000 with /@vite/client, but #app is empty and the macro has 0 height | Vite started without FORGE_TUNNEL=1 — @forge/bridge is the Storybook stub | Restart Vite with FORGE_TUNNEL=1 PORT=8080 pnpm start:local:raw |
| Iframe loads but shows OLD code / wrong git branch in the dev bar | Stale Vite from another worktree squatting on :8080 | See Stale Vite from another worktree |
Prompts can not be meaningfully rendered in non-TTY environments from forge:install:dev / forge:upgrade:dev | .env.forge / .env.forge.local missing → placeholders not substituted → forge prompts for site | Create the env files in this worktree (see Setup). NOT a real TTY problem despite the message |
| Macros show old description/title | Confluence cached the old assets | Hard-refresh (Cmd+Shift+R) |
| Forge appends "(Development)" to macro names | Normal for dev environments | Won't appear in staging/production |
| Lint warnings about deprecated egress | Old permission format in manifest.yml | Safe to ignore; tunnel still starts |
Stale Vite from another worktree
This bites HARD in multi-worktree setups. Symptoms: the iframe loads, the page renders, but you see the wrong branch in the dev bar (e.g. feat/old-thing:abc1234 instead of your current branch), and the code on screen is from a different worktree. Hard-refresh doesn't help. Restarting the tunnel doesn't help. The deploy was successful and forge install list shows the install is up-to-date.
What's happening: forge tunnel proxies HTTP requests for the app's frontend resources to localhost:8080. It does not start the Vite dev server itself. If a vite dev --port 8080 from another worktree is already running (e.g. you ran pnpm start:local in ~/workspaces/zenuml/conf-app-public earlier this week and forgot), THAT Vite is what answers — its cwd is the other worktree, so it serves that branch's source files. The tunnel is doing exactly what it was told.
Diagnose:
pgrep -lf "vite/bin/vite.js"
# or
lsof -iTCP:8080 -sTCP:LISTEN
# then
ps -p <pid> -o pid,command # check the binary path — that path's parent dir is the cwd Vite reads from
The vite/bin/vite.js path will be inside <some-worktree>/node_modules/.... If that worktree isn't yours, that's the bug.
Fix:
kill <pid> # kill the stale Vite
cd <your-worktree>
FORGE_TUNNEL=1 PORT=8080 pnpm start:local:raw # start a fresh Vite from the right worktree
# then in another terminal: pnpm forge:tunnel
Verify the right Vite is up before opening the browser:
curl -s http://localhost:8080/src/components/Viewer/GenericViewer.vue \
| head -1 | grep -oE 'VITE_APP_GIT_BRANCH[^,]+'
# Expected: VITE_APP_GIT_BRANCH": "<your-branch>"
The tunnel itself listens on a separate port (printed as Listening for requests on local port XXXXX...) and the browser sees http://localhost:8000/... for the iframe — these are intermediaries, the content still comes from whatever is at :8080.
Tips
- The tunnel terminal output is the canonical signal that it's working — keep an eye on it
forge install list -e <env>answers "which sites have this version installed"- The tunnel only proxies your authenticated session — share-tested features need a real deploy
VITE_APP_GIT_BRANCH/VITE_APP_GIT_HASHshown in the dev bar = ground truth for "which worktree is Vite serving from." Trust the dev bar, not your assumption.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |