Getting Started

There is currently no single canonical entry point into the Hypermedia system.

Different developers want different kinds of programmatic access, and the protocol exposes multiple layers. Which path you choose depends on how deeply you want to integrate and how much of the system you want to reimplement yourself.

This page describes the available (and planned) entry points, what they enable, and the tradeoffs involved.

Protocol-Level Participation (Without Seed Hypermedia Software)

Some developers may want to participate in the Hypermedia Network without relying on Seed Hypermedia’s implementation.

This path requires working directly with the underlying protocols, primarily libp2p and, in some cases, the HTTPS-based protocol surface. These interfaces exist today, but they are still evolving and should be considered unstable.

This approach is intended for teams building independent implementations, alternative nodes, or experimental clients that interoperate at the protocol level.

It offers the greatest flexibility, but also comes with high complexity and limited tooling.

Building a Custom Frontend on Top of Hypermedia

Developers who want to create a custom user interface without reimplementing the protocol can build on top of Hypermedia itself.

In this model, you run the Hypermedia daemon and communicate with it over gRPC or HTTPS, optionally running parts of the web server software. This allows you to design custom experiences while relying on an existing, working implementation of the protocol.

This approach is well-suited for frontend teams and product builders, and represents a middle ground between flexibility and complexity.

Using the Command-Line Interface (CLI)

Hypermedia provides a command-line interface that connects to the system over HTTPS.

The CLI can be used directly by developers for exploration, scripting, and automation. It is also used internally by an agent skill, which makes it one of the most concrete and battle-tested entry points available today.

While the ergonomics are still evolving, the CLI is currently one of the lowest-friction ways to interact with the system.

Defining Custom Block Types

Developers who want to define custom block types need to work closer to the core.

At the moment, this requires forking the codebase, as there is no stable plugin or extension API yet. This path is intentionally limited and primarily aimed at core contributors and experimental work.

It offers deep control, but at the cost of invasive changes and forward-compatibility.

Planned: TypeScript Library

A TypeScript library is planned but not yet available.

Once released, it is expected to become a primary entry point for web developers and application builders, offering a higher-level and more stable interface than the protocol or daemon APIs.

For now, developers should treat Hypermedia as a layered system and select the highest-level interface that meets their needs.