Skip to content

ZenUml/conf-app / .claude/skills/forge-tunnel

forge-tunnel

Verified

Run 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 tunnel start or restart, inspect the whole machine for an existing pnpm forge:tunnel parent and @forge/cli ... tunnel child. 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 staging and -e production fail with "Cannot create tunnels outside of the development environment".

  • The tunnel is identity-gated: it serves ONLY the browser logged in as the FORGE_EMAIL account (set in .env.forge.local; ./scripts/forgex whoami prints 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 in CLAUDE.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 the FORGE_EMAIL account 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/current and match its accountId against ./scripts/forgex whoami. agent-browser profiles lists the others. --profile reuses existing login state; no credential entry is involved, and frame/eval into the OOPIF keep working.

    Confirm it is actually working, in one check: inside the macro iframe, location.host must be localhost:8000 (not …cdn.prod.atlassian-dev.net) and the scripts must be /@vite/client + /src/…, not assets/index-<hash>.js. From the shell, lsof -i :8080 | grep -c ESTABLISHED must 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:lite is not needed for frontend edits — a page reload is enough.

  • ./scripts/forgex is the canonical entry point — it loads .env.forge + .env.forge.local and substitutes {{VAR}} placeholders. All pnpm forge:*:dev scripts use it. Don't call forge directly 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 deploy packages whatever is in dist/ — 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:raw separately to put a Vite dev server there. Both variables are required:

    • PORT=8080 — pnpm start:local goes through Portless and binds a random internal port, but manifest.yml hardcodes tunnel.port: 8080, so the tunnel finds nothing.
    • FORGE_TUNNEL=1 — in serve mode vite.config.mjs aliases @forge/bridge to the Storybook stub (src/stubs/forge-bridge.ts) unless this is set. With the stub, view.getContext() returns null, the iframe loads Vite modules but #app stays 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 though accountId is attached to the payload. Empirically verified on 2026-05-16: a console.log probe in src/export.js produced 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 on adfExport code (src/export.js in this repo), forge deploy -e development is required after each change — forge tunnel alone will not pick up your edits. See docs/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.net may have its install in env development (not lite-dev). When the user says "test on lite-dev", that's the site — forge install list is 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.local internally; $VAR is 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

AppAPP_ID.env.forge symlink target
Lite8ad26115-211f-4216-971b-0540f606303d.env.forge.lite
Fulld9e4002b-120b-426b-834b-402a4a5adce7.env.forge.full
Diagramly01ede8b1-4e88-451a-b9ef-89eeef93afaf.env.forge.dia

Troubleshooting

ProblemCauseFix
"Cannot create tunnels outside of the development environment"Using -e staging / -e productionUse a development env name
"The scopes or egress URLs differ from most recent deployment"Manifest changed since last deploy to this envRun pnpm forge:deploy:dev first
"Could not find an installation" on --upgradeApp not installed on that site yetFresh 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 confirmationRun 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 siteUse 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 pageWrong env, wrong site, or app not installed thereforge install list -e <env> to verify
Tunnel returns 500 AggregateError / Failed to connect to localhost:8080No Vite dev server on :8080 — tunnel proxies but doesn't hostRun 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 heightVite started without FORGE_TUNNEL=1 — @forge/bridge is the Storybook stubRestart Vite with FORGE_TUNNEL=1 PORT=8080 pnpm start:local:raw
Iframe loads but shows OLD code / wrong git branch in the dev barStale Vite from another worktree squatting on :8080See 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 siteCreate the env files in this worktree (see Setup). NOT a real TTY problem despite the message
Macros show old description/titleConfluence cached the old assetsHard-refresh (Cmd+Shift+R)
Forge appends "(Development)" to macro namesNormal for dev environmentsWon't appear in staging/production
Lint warnings about deprecated egressOld permission format in manifest.ymlSafe 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_HASH shown in the dev bar = ground truth for "which worktree is Vite serving from." Trust the dev bar, not your assumption.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall