# Lens Hub

> The catalog and registry front door for Lens typed agent-system artifacts —
> kits of kind `sandbox`, `mixin`, `connector`, published as OCI artifacts and pulled by reference
> with the `lns` CLI.

The hub also indexes the `image` repositories those kits run. An image
is an OCI image and nothing more: it declares no kind, carries no
specification, and is pushed and pulled with any OCI client rather than
authored as a kit. It is listed, searchable and filterable as `family=image`
like any other repository.

The catalog is a database, so `https://hub.lns.run/api/search` is how to enumerate it: it answers JSON
to anonymous callers, narrows on `q`, `family`, `sort` and `page`, and is
exhausted when `has_additional` is false. A single repository's specification is
a file at `https://hub.lns.run/repository/spec/{namespace}/{name}`, YAML unless `format=json`, and
`v=<tag>` asks for a version other than the newest. Only public repositories
answer an anonymous caller: a private one is absent rather than redacted, so its
name reads exactly like a name nobody has taken.

The pages themselves negotiate: `Accept: text/markdown` on the explore listing
or on any repository page answers the same URL as markdown — the catalog as a
table that names its own query parameters, a repository as its README with the
run command and versions. The explore listing is public-only in every form —
the page, the markdown and the search API — and a session never widens it.

## Catalog

- [Search API](https://hub.lns.run/api/search): every public repository as JSON, one page at a time
- [Explore](https://hub.lns.run/): the same listing as a page, with the family rail and sort

## Publishing

- [Publish an artifact](https://hub.lns.run/publish): sign the CLI in, author a kit, push it, then make it public
- [Authoring guide](https://github.com/lensapp/lens-sandbox/blob/main/docs/running-workloads.md): what belongs in an `lns.yaml`, per kind
- [Sandbox spec](https://github.com/lensapp/lens-sandbox/blob/main/docs/sandbox-spec.md): the reference for every block

## Optional

- [Registry endpoint](https://hub.lns.run/v2): OCI Distribution — artifact bytes are never anonymous, so a pull authenticates with a personal access token