Tool center

Tool Center

The Tool Center is Sencai’s Docker image browser. It lets you search Docker Hub, GitHub Container Registry (GHCR), and Quay.io, and connect your own private Docker registries so their images show up alongside public ones. It is a browser, not a deployment pipeline — the Tool Center does not deploy images to your instances.

Routes

Route	Purpose
/gravity/toolcenter	Docker Hub browser, with tabs for GHCR and Quay.io
/gravity/toolcenter/detail/:id	Image detail page. :id is the URL-encoded namespace/name. Add ?source=ghcr or ?source=quay to view an image from that registry instead of Docker Hub.
/gravity/toolcenter/registries	List of your organization’s custom registries
/gravity/toolcenter/registries/:id	Detail view of a single custom registry — connection status, image list, manual path search

Browsing Docker Images

Search

1. Go to Tool Center in the main navigation
2. Use the search bar to find images by name (e.g., “nginx”, “postgres”, “redis”)
3. Switch between the Docker Hub, GHCR, and Quay.io tabs to search each registry separately

Image Details

Click any image to open its detail page, which shows:

• Description and official/verified badge (Docker Hub)
• Tags — available versions
• Stars and pulls as popularity indicators
• Pull command for the selected registry (e.g., docker pull nginx:latest, docker pull ghcr.io/namespace/name:tag)
• External link to the image’s page on Docker Hub, GitHub, or Quay.io

Custom Registries

If your organization uses a private Docker Registry v2 endpoint (GitLab Container Registry, Harbor, GHCR with a personal token, or a self-hosted registry), you can connect it under Organization Settings → Docker Registries. Connected registries are managed against the custom-registry content-type in the backend and are scoped to your organization.

Add a Custom Registry

1. Go to Organization Settings → Docker Registries
2. Click Add Registry
3. Fill in:
   • Name — a friendly label for the registry
   • URL — the registry’s Docker Registry v2 host (e.g., registry.gitlab.com), without the https:// prefix
   • Username (optional) — used for Basic auth during token exchange (for GitLab PATs, use oauth2; for Harbor, use the robot account name). Leave empty to send the token directly as a Bearer credential.
   • Token / Password — a personal access token or password. It is encrypted at rest with AES-256-GCM and is never returned by the API once saved.
   • API URL (optional) — a GitLab or Harbor API base URL (e.g., https://gitlab.example.com) used for auto-discovery of repositories, described below
4. Click Save, then use Test Connection to verify the registry responds

After a successful test, the registry’s status becomes ok and its status badge updates; a failed credential check shows unauthorized, and other connection problems show error.

How authentication works

Many registries (GitLab Container Registry, Harbor, GHCR) reject plain Basic auth on the Docker Registry v2 API. The Tool Center performs the standard Docker Registry v2 bearer-token exchange instead:

1. GET /v2/ — if the registry responds 401 with a WWW-Authenticate: Bearer realm="...",service="...",scope="..." header, proceed to step 2
2. GET {realm}?service=...&scope=... with Basic auth (username + token) — exchanges the credential for a short-lived Bearer JWT
3. GET /v2/ again with Authorization: Bearer {jwt} — expected to return 200 OK

This flow runs for connection tests, repository listing, and tag lookups.

Browsing repositories

Once a registry’s status is ok, its detail page attempts to list repositories. Two paths exist:

• Registry catalog (/v2/_catalog) — used automatically if no API URL is set. Some registries (notably GitLab Container Registry with a personal-access-token user) restrict this endpoint to admin credentials, in which case it returns no results.
• API-based auto-discovery — if an API URL is configured (GitLab), the backend queries the GitLab API for projects and their registry repositories instead of relying on /v2/_catalog. This path is still being validated end-to-end — confirm it works against your specific GitLab instance before relying on it.

Regardless of which discovery path is used (or if neither returns results), you can always use Browse by path: enter a known repository path (e.g., group/project) and the Tool Center fetches its tags directly from the registry, bypassing the catalog restriction.

Remove a Custom Registry

Registries are removed as a soft-delete — the record is marked inactive and no longer appears in the UI, but is retained rather than deleted outright. Contact your organization admin if you need a registry fully purged.

Favorites

You can mark individual images in a custom registry as favorites using the star icon on each image card.

This is a per-browser feature, not a per-organization one: favorites are stored in your browser’s localStorage under the key sencai:registry-favorites and are not shared with teammates or synced across your own devices. There is no “Most Used in your organization” filter — the only filter available is the local All / Favorites toggle scoped to your own browser.

Known Limitations

• GHCR tag data — GHCR search results come from the GitHub Repositories API, not the GitHub Packages API, so a result may not have a published ghcr.io package; the tags list can be empty even for a valid repository.
• Registry catalog restrictions — GitLab Container Registry and restricted Harbor accounts often cannot list all repositories via /v2/_catalog; use Browse by path or the API-based auto-discovery instead.
• Security scanning — a Test button appears on registry image cards, but it currently only shows a “coming soon” notice; scanning is not implemented yet.
• No deployment from Tool Center — the Tool Center only browses and searches images. To run a container on an instance, use the relevant instance/deployment tooling elsewhere in the platform; this page does not cover that flow.

Troubleshooting

Q: A custom registry shows “Authentication failed” (unauthorized)

A: Check your username/token combination. For GitLab personal access tokens, set the username to oauth2. For Harbor, use the robot account name as the username. If the error persists, try regenerating and re-saving the token.

Q: No repositories appear for my custom registry even though the status is “Connected”

A: The registry’s /v2/_catalog endpoint may be restricted for your credentials. Add an API URL to enable GitLab-based auto-discovery, or use Browse by path to fetch tags for a repository you already know the path to.

Q: An image I expect to find isn’t showing up in Docker Hub/GHCR/Quay search

A: Try the full namespaced name (e.g., “library/postgres” instead of just “postgres”), or check the other tabs — the image may live on a different registry than the one you’re currently searching.