Ephemeral environments that cut your cloud bill

On pull request open, a GitHub Action runs wf up with the PR number baked into the instance name. Wayfinder reads the same Wayfinder.yaml you use in production, provisions every dependency the manifest declares, and writes the preview URL into a file. A second step posts the URL back to the PR as a comment.

What wf up actually does, step by step

• Resolves a stack instance. Named wfpreviews-pr123 from the PR number, so the close workflow can find the same instance later without state files or tag scans.
• Provisions managed dependencies declared in the manifest: databases, queues, object stores, secrets. Wayfinder wires the workload to each one dynamically with a cloud-native identity and a restricted policy. No shared access, no reduced cloud security.
• Deploys the workload. Container deployments on Kubernetes, Lambdas, API Gateway and any other cloud resources your app needs. Mix and match in a single manifest.
• Wires DNS and TLS on your preview zone (pr123.previews.dev.example.com). Certificate issued, record live.
• Vends short-lived credentials for everything it created. The job never sees a raw cloud key.
• Writes preview.json with each component's outputs from the deploy (URLs, hostnames, resource IDs). The next CI step reads the URL out of it and posts the comment on the PR.

Kubernetes-based app

The workflow we use to ship Wayfinder itself. The container app deploys into a per-PR namespace on a dedicated preview cluster.

deploy-ui-preview:
  runs-on: ubuntu-latest
  container:
    image: ${{ vars.CI_WFTOOLBOX_IMAGE }}
  steps:
    - uses: actions/checkout@v4
    - name: Deploy UI to PR preview environment
      id: deploy
      env:
        WAYFINDER_SERVER:      ${{ vars.CI_WAYFINDER_SERVER }}
        WAYFINDER_TENANT:      ${{ vars.CI_WAYFINDER_TENANT }}
        WAYFINDER_WORKSPACE:   ${{ vars.CI_WAYFINDER_WORKSPACE }}
        WAYFINDER_ENVIRONMENT: ${{ vars.CI_WAYFINDER_ENV_DEVELOP }}
        WAYFINDER_TOKEN:       ${{ secrets.UI_PREVIEWS_WAYFINDER_TOKEN }}
      run: |
        export ENV="wfpreviews-pr${{ github.event.pull_request.number }}"

        wf up -i ${ENV} \
          --target k8s=${WAYFINDER_WORKSPACE}/${WAYFINDER_ENVIRONMENT}/${{ vars.DEVELOP_HOST_CLUSTER }}:${ENV} \
          --dns-zone previews.dev.wayfinder.run \
          --out-file ./preview.json

        echo "PREVIEW_URL=$(jq -r '.componentOutputs.wfui.url.value' ./preview.json)" >> $GITHUB_OUTPUT

--target k8s=... picks the host cluster and the namespace to land in. --dns-zone says where to publish the preview URL. --out-file is how the URL gets back to the PR comment job; the last line plucks it out of the JSON.

Non-Kubernetes app (serverless on AWS)

The same wf up handles a fully serverless stack (Lambdas, API Gateway, DynamoDB, S3, CloudFront) when that's what the manifest declares. No --target k8s; just the manifest and a DNS zone. The PR number still drives the instance name, the close workflow still finds it the same way.

deploy-api-preview:
  runs-on: ubuntu-latest
  container:
    image: ${{ vars.CI_WFTOOLBOX_IMAGE }}
  steps:
    - uses: actions/checkout@v4
    - name: Deploy AWS preview environment
      env:
        WAYFINDER_SERVER:      ${{ vars.CI_WAYFINDER_SERVER }}
        WAYFINDER_TENANT:      ${{ vars.CI_WAYFINDER_TENANT }}
        WAYFINDER_WORKSPACE:   ${{ vars.CI_WAYFINDER_WORKSPACE }}
        WAYFINDER_ENVIRONMENT: ${{ vars.CI_WAYFINDER_ENV_DEVELOP }}
        WAYFINDER_TOKEN:       ${{ secrets.API_PREVIEWS_WAYFINDER_TOKEN }}
      run: |
        export ENV="apipreviews-pr${{ github.event.pull_request.number }}"
        export VERSION="pr${{ github.event.pull_request.number }}-${{ github.sha }}"

        wf up -f ./aws/Wayfinder.yaml \
          -i ${ENV} \
          --dns-zone previews.dev.example.com \
          --env-var VERSION=$VERSION \
          --out-file ./preview.json

The result, in either case, is a real working environment shaped like production (the same manifest, the same identity model, the same dependencies) that reviewers can click before merge. Different runtime, identical lifecycle.

The half of the story that keeps the bill flat. Once the PR closes (most often a clean merge after review, but also if it's declined or simply abandoned) a separate workflow runs wf down against the same instance name. Wayfinder walks the instance's resource graph and removes every node on it.

name: Pull Request closed
on:
  pull_request:
    types: [closed]

jobs:
  teardown-ui-preview:
    runs-on: ubuntu-latest
    container:
      image: ${{ vars.CI_WFTOOLBOX_IMAGE }}
    steps:
      - uses: actions/checkout@v4
      - name: Clean up preview environment
        env:
          WAYFINDER_SERVER:      ${{ vars.CI_WAYFINDER_SERVER }}
          WAYFINDER_WORKSPACE:   ${{ vars.CI_WAYFINDER_WORKSPACE }}
          WAYFINDER_ENVIRONMENT: ${{ vars.CI_WAYFINDER_ENV_DEVELOP }}
          WAYFINDER_TENANT:      ${{ vars.CI_WAYFINDER_TENANT }}
          WAYFINDER_TOKEN:       ${{ secrets.UI_PREVIEWS_WAYFINDER_TOKEN }}
        run: |
          export ENV="wfpreviews-pr${{ github.event.pull_request.number }}"
          wf down -e ${WAYFINDER_ENVIRONMENT} -i ${ENV} || true

Wayfinder walks the resource graph

Every wf up records what it created: the workload, every managed resource that backed it, every binding between them, every credential it minted. wf down traverses that graph in dependency order, deleting leaves first so nothing gets stranded with a parent still alive. No tag scans, no "best effort". Wayfinder removes the things it knows it provisioned, in the order they can safely come down.

What goes, in order

• Workload first. The Kubernetes namespace and everything inside it, or the Lambdas, API Gateway routes and CloudFront distribution that fronted them.
• The wiring between workload and dependencies. Queue subscriptions, event-bus rules and scheduled triggers (the bindings Wayfinder set up to connect your container, Lambda or other runtime to its data services) come down before the services themselves.
• Managed cloud resources. Databases, object-storage buckets, secret-manager entries, KMS keys, ECR images, each removed once nothing still references it.
• DNS and TLS. The record on your preview zone is withdrawn; the certificate is revoked or released. The URL stops resolving the moment the record is gone.
• Identity and access. Every workload identity, IAM role, cluster role binding and short-lived credential Wayfinder created is removed.
• The stack instance record. The stack instance is Wayfinder's record of every cloud relationship it set up for this PR. Once those are all gone in the cloud, Wayfinder clears its own record too, so the next PR with the same number starts clean.

If any single step fails (a Kubernetes deployment that won't drain, a network that won't delete, a bucket with delete protection turned on) Wayfinder pauses on that node, surfaces it in the job log, and lets you re-run wf down to resume. A half-deleted instance never silently turns into an orphan.

The same primitives that drive PR previews drive your inner dev loop. wf up on your laptop creates a personal stack instance with the same Wayfinder.yaml, the same managed dependencies, and the same identity model as production.

From your AI editor

Wayfinder's MCP server plugs into Claude Code, Cursor, Continue or any MCP-capable AI editor. Your agent can spin a stack up or take it down with a single instruction, and read the deploy result and running workload's logs without you leaving the conversation.

• Drive wf up and wf down from your agent. Ask it to spin the stack up or tear it down, and the MCP server runs against the workspace and environment you're working in. No terminal context switch, no remembered command.
• Fast feedback in the editor. Deploy status, the preview URL and the running workload's logs stream back into the conversation, so you see what worked (and what didn't) without switching context.

From the terminal

The same flow, scriptable, for when you'd rather drive it from a shell, or wrap it in a Makefile, a justfile, or a pre-commit hook.

wf use workspace <your-workspace>
wf use environment dev

# No -i flag: Wayfinder generates a friendly
# name (e.g. "busybeaver") and remembers it.
wf up -f ./Wayfinder.yaml

# Iterate. Wayfinder updates the same instance.
wf up -f ./Wayfinder.yaml

# Done for the day.
wf down

Each developer (or each team) gets their own stack instance in the shared dev environment. Run wf up again later and Wayfinder updates that instance instead of spawning a new one. Multiple instances run side by side in the same environment, so teams can iterate and test in parallel without tripping over each other, and any one of them can be torn down without affecting the others.

Why “like production” matters

• One manifest, end to end. The Wayfinder.yaml you run on your laptop is the one CI runs for previews and the one that ships to production. No dev variant to drift.
• Real managed services, not stand-ins. Your code talks to the same database engine, the same queue, the same object store it will in production. SDK quirks, IAM behaviour, latency shape, all real.
• Scoped identity per developer. Each instance gets its own IAM role and short-lived credentials. No shared service account, no “dev-everything” key in ~/.aws/credentials.
• Disposable by design. Hit wf down at the end of the day and the entire stack goes with it, using the same teardown the PR close hook uses. Tomorrow's cost is tomorrow's choice.
• No cluster-admin required. Wayfinder negotiates the host environment for you, so you don't need elevated rights on the shared cluster or cloud account just to test your own code.

The PR close hook does the heavy lifting. A handful of patterns on top take preview spend to a rounding error, catch the rare straggler, and turn “what is this thing?” into a question you never have to ask.

Make orphans impossible to hide

• One instance per PR, named from the PR number. Avoid hashing branch names or commit SHAs. A name you can read at a glance is a name you can grep, audit and reconcile against the list of open PRs.
• Own the workflow that calls wf down. The PR-close workflow above is the primary trigger. Because Wayfinder only marks an instance gone once the cloud side is fully cleaned up, anything that fails to tear down stays visible in Wayfinder for you to re-run, not silently sitting in your cloud bill. You don't end up with orphaned resources.

Cap blast radius before it starts

• Land previews on a small, dedicated host. Wayfinder targets whichever cluster or cloud account you point it at, so put previews on an isolated, cheap one. Small node types, short lifetimes, easy to mass-delete if you ever need a clean slate.
• Use the preview environment's plan catalogue. Plans are scoped per environment, so a resource that resolves to a production-sized managed database in prod can resolve to a smaller one in previews. Same manifest, different cost profile.

The pull request's open/closed state is the signal. Everything else flows from owning that one workflow.