Web Bridge Developer Guide v1.0

A strategic gateway between web 2.0 and distributed applications

May 2025

Overview

The Holo Web Bridge is a transformative infrastructure component enabling traditional web apps to access Holochain DHT data using HTTPS. It makes distributed content available in a read-only format to web clients, extending Holochain’s reach into today's Internet.

Technical Implementation Guide

Holochain HTTP Gateway and Holo Web Bridge Relationship

The bridge connects to Holochain Cloud Nodes using the Holochain HTTP Gateway. Each cloud node is exposed via a public URL, routing requests to the first responding node. Since Holochain ensures eventual consistency, concurrent requests may return different values temporarily.

Configuration Process

Allowed zome functions must be listed via the HC_GW_ALLOWED_FNS_ environment variable.

For example:

HC_GW_ALLOWED_FNS_=main/list_mews,main/count_likes

URL Format Specification

GET request format:

https://<host>/<dna-hash>/<coordinator-id>/<zome>/<function>?payload=<payload>

• host: Your deployment base URL
• dna-hash: Base64url DNA hash
• coordinator-id: App instance ID (UUID)
• zome: The module name
• function: Function to call
• payload: Optional base64url-encoded JSON input

Examples

• No payload: https://web-bridge.holo.hosting/.../content/get_pdf
• With payload: https://web-bridge.holotest.dev/.../get_attestation?payload=ey...Qo=

Payload Encoding Instructions

1. Start with JSON: {"stream_id":"xx","content":"Hello"}
2. Base64url encode it: eyJzdHJl...sImNvbnRlbnQiOiJIZWxsbyJ9

HTTP Response Codes

Code	Meaning	Example
200	Success	{"data":"result"}
400	Bad request	{"error":"Invalid payload"}
403	Access denied	{"error":"Function not exposed"}
404	Not found	{"error":"No app found"}
405	Method not allowed	Used POST instead of GET
500	Internal error	{"error":"Conductor error"}

Response Payload Handling

Unlike the legacy Holo Network, which used msgpack decoding via Chaperone, the Web Bridge returns raw JSON. Developers must account for possible data structure differences (e.g., Uint8Array values).

Technical Best Practices

• Only expose safe (read-only) functions.
• Keep payloads under 10KB to avoid 400 errors.
• Always use HTTPS (enabled by default in production).

Implementation Path

1. Identify safe functions
2. Send the allowlist to the Holo deployment team
3. Construct testable GET URLs
4. Use curl or browsers to validate responses
5. Build front-end logic to process the JSON result

Important Considerations

• Read-only behavior is not enforced — any exposed function will run.
• Allowed function configuration requires manual deployment support.

Strategic Application Benefits

• Extended Reach: Expose Holochain content to web apps without native Holochain integration.
• Read-Only Access: Enables secure data exposure while preserving DHT integrity.
• Data Sovereignty: Leverages agent-centric architecture while expanding accessibility.

Self-Service Evolution Roadmap

Future versions will include:

• Cloud Console: Configure and monitor deployments via UI
• API Layer: Manage function allowlists, metrics, and integrations programmatically

Future Enhancements

• Authentication support
• Enhanced security and access control
• Direct management through Holo's application interface

Conclusion

The Holo Web Bridge enables seamless access to distributed data from web clients. By following this guide, developers can extend their Holochain applications' accessibility while preserving the principles of data integrity, autonomy, and decentralization.

Download Full PDF