Graph Compose

Local Development

Test your Graph Compose workflows against local services by exposing them through an ngrok tunnel.

Why you need a tunnel

Graph Compose runs in the cloud. When a workflow executes, it sends HTTP requests to the URLs you configure in each node. If your service runs on localhost:3000, Graph Compose cannot reach it directly. A tunnel gives your local server a public URL that Graph Compose can call.

graph LR A[Graph Compose] -->|abc123.ngrok.io| B[ngrok] B -->|tunnel| C[localhost:3000]

Set up ngrok

1. Install

brew install ngrok

You can also download it directly from ngrok.com/download.

2. Connect your account

Sign up for a free account at ngrok.com, then add your auth token:

Add auth token

ngrok config add-authtoken YOUR_TOKEN

3. Start the tunnel

Start your local server, then open a tunnel to its port:

Create a tunnel

ngrok http 3000

ngrok prints a forwarding URL like https://abc123.ngrok.io. Use this URL in your workflow nodes wherever you would normally use localhost.

Use the tunnel in a workflow

Replace your production URLs with the ngrok URL. Once you confirm the workflow works, swap the URLs back to production before deploying.

import { GraphCompose } from '@graph-compose/client'

const graph = new GraphCompose({
  token: process.env.GRAPH_COMPOSE_TOKEN
})

graph
  .node("process_user")
    .post("https://abc123.ngrok.io/api/users")
    .withBody({
      name: "{{ context.name }}",
      email: "{{ context.email }}"
    })
  .end()

  .node("enrich_data")
    .post("https://abc123.ngrok.io/api/enrich")
    .withBody({
      userId: "{{ results.process_user.data.id }}"
    })
    .withDependencies(["process_user"])
  .end()

When you restart ngrok, you get a new URL. Update your workflow nodes with the new URL, or use a paid ngrok account with a fixed domain to avoid this.

Inspect traffic

ngrok includes a local web inspector at http://localhost:4040 while the tunnel is running. You can:

  • View every request Graph Compose sends to your service, including headers and body
  • See your service's response, status code, and timing
  • Replay requests to re-test without re-running the workflow

This is especially useful for debugging webhooks. Configure your workflow's webhook URL to point at the ngrok tunnel and inspect the callback payloads in real time.

Tips

  • Run ngrok in a separate terminal window or use a terminal multiplexer like tmux so the tunnel stays open while you work.
  • Store the ngrok URL in an environment variable. When the URL changes, update it in one place.
  • Use ngrok http --inspect 3000 to enable the traffic inspector (enabled by default on most setups).
  • For team environments, a paid ngrok account with a reserved domain means everyone can use a stable URL.

Next steps

WebhooksExecuting WorkflowsQuickstart