Stacker PIPE Endpoint Discovery - What Works and What Doesn't

What We Tested

We deployed Directus, Chatwoot, Stirling-PDF, and WordPress on the same server and ran stacker pipe scan and stacker pipe create to test endpoint discovery. Here's what the agent finds - and what it misses.

Quick Answer

What the Agent Discovers

The agent's probe scans for three types of endpoints:

1. OpenAPI/Swagger specs - at standard paths like /api/docs, /swagger.json, /openapi.json
2. HTML forms - on the root page of web applications
3. REST API patterns - at standard paths like /api, /api/v1, /api/v2

Results by Application

WordPress (Contact Form 7) - Discovered

The agent successfully finds HTML forms on WordPress pages:

{
  "forms": [{
    "action": "/contact#wpcf7-f5-p6-o1",
    "fields": ["your-name", "your-email", "your-subject", "your-message"]
  }]
}

WordPress exposes forms directly on its pages, which the agent's HTML probe detects. This is the most reliable discovery path.

Directus - Not Discovered

Directus exposes its REST API at /items/* and GraphQL at /graphql. Neither path matches the agent's standard patterns. The probe returns empty.

Workaround: Use manual endpoints:

stacker pipe create directus chatwoot \
  --source-endpoint "POST /items" \
  --target-endpoint "POST /api/v1/conversations"

Chatwoot - Not Discovered

Chatwoot's REST API lives at /api/v1/*. The agent checks /api and /api/v2 but not /api/v1. Returns empty.

Workaround: Specify endpoints manually.

Stirling-PDF - Not Discovered

Stirling-PDF's internal API uses non-standard paths. The probe finds nothing.

Hanko - Not Discovered

Hanko's REST API at /v1/* doesn't match any standard pattern.

Container Resolution - Works

The agent correctly resolves container names via my.stacker.service labels:

Container name resolved via compose service label
app_code="project-directus-1" resolved_name="project-directus-1"

Network Connectivity - Works

After connecting the agent to the project network (docker network connect), the agent can reach containers on their internal IPs.

Why Some Apps Aren't Found

The agent probe checks a fixed set of paths:

• /api/docs, /swagger.json, /openapi.json - OpenAPI specs
• /api, /api/v1, /api/v2 - REST patterns
• Root page - HTML forms

Apps that use non-standard paths (Directus at /items/*, Chatwoot at /api/v1/*) are invisible to the probe. The probe doesn't follow redirects or check app-specific paths.

Workarounds

Option 1: Use Apps with Standard API Patterns

Apps that expose OpenAPI specs or REST APIs at /api/* paths are discovered automatically. WordPress with Contact Form 7 is the most reliable for form discovery.

Option 2: Manual Endpoint Specification

Bypass discovery entirely with explicit endpoints:

stacker pipe create <source> <target> \
  --source-endpoint "METHOD /path" \
  --target-endpoint "METHOD /path" \
  --source-fields field1,field2 \
  --target-fields field1,field2 \
  --name "my-pipe"

Option 3: Use --container Flag

The direct_container probe scope finds more endpoints than remote_app:

stacker pipe scan --app <APP> --container <NAME> --protocols html_forms

Next Steps for Stacker

1. Enhance agent probe to check more paths (including app-specific ones)
2. Allow manual endpoint specification in stacker pipe create (already available)
3. Use app documentation to pre-populate endpoint discovery
4. Support OpenAPI spec URLs as input to the probe

Frequently Asked Questions

Why doesn't the agent find Directus endpoints?

Directus uses /items/* instead of the standard /api/* path. The agent's probe only checks standard paths. Use manual endpoint specification as a workaround.

Can I improve endpoint discovery?

Use the --container flag with stacker pipe scan to force direct container probing. This finds more endpoints than the default remote_app scope.

Will Stacker add support for non-standard API paths?

The manual endpoint feature already covers this. Future updates may add app-specific probe patterns or allow custom OpenAPI spec URLs.

What's the most reliable way to create pipes?

Use manual endpoints. They work regardless of whether the app is running, what API paths it uses, or which Docker network the agent is on.

Key Takeaways

• Endpoint discovery works for apps with standard /api/* paths and HTML forms
• Non-standard paths (Directus, Chatwoot, Hanko) require manual endpoints
• Container resolution and network connectivity work correctly
• Manual endpoint specification is the most reliable approach
• The --container flag finds more endpoints than the default probe scope