---
url: https://docs.hostly.ninja/concepts/hostly-registry.md
---
# Hostly Registry

The **Hostly Registry** is Hostly's private storage for container images. It lets you keep images
next to the workspace in which you intend to use them.

The registry stores images, but it does not build or run them. An image becomes a running
application only when you use its reference in a Hostly deployment.

```text
Build an image -> push it to the Hostly Registry -> deploy it as a Hostly service
```

## How registry content is organized

Hostly organizes registry content by workspace:

```text
Hostly Registry
└── workspace repository
    ├── image
    │   ├── tag
    │   └── another tag
    └── nested/image
        └── tag
```

### Registry

The registry is the service that stores all Hostly images. Its address is:

```text
registry.hostly.ninja
```

### Workspace repository

Each workspace has its own repository in the registry. The repository name is always the workspace
slug, which keeps images separated between workspaces.

For a workspace with the slug `acme`, the repository starts with:

```text
registry.hostly.ninja/acme
```

Hostly uses **repository** for this workspace-owned part of the image reference. Other container
registry tools may use the same word for the complete path after the registry host.

### Image and tag

An **image** is a named container image inside the workspace repository. Image names can contain
multiple path segments, such as `backend/api`.

A **tag** is a label for a particular version of an image. One image can have several tags, for
example `1.4.2`, `stable`, and `latest`.

## Reading a Hostly image reference

A complete image reference contains the registry, workspace repository, image name, and tag:

```text
registry.hostly.ninja/acme/api:1.4.2
|-------------------| |--| |-| |---|
      registry        repo image  tag
```

A nested image name works the same way:

```text
registry.hostly.ninja/acme/backend/api:1.4.2
```

The registry page in Hostly shows the correct registry address and copyable references for your
images and tags.

## Tags can change

A tag is a mutable label. Pushing new image content with an existing tag moves that tag to the new
version.

For predictable deployments, prefer versioned tags such as `1.4.2`. A general tag such as `latest`
can be useful during development, but it does not make a running service update automatically.
Hostly uses the image version the tag points to when the service's containers start. Changing a tag
in the registry afterward does not change the running service; restarting or deploying it again
picks up the new version.

## Login codes and registry sessions

You need a registry session to push images to or pull images from the Hostly Registry.

The login flow has two distinct credentials:

1. Hostly creates a short-lived, one-time login code.
2. You use the displayed Docker login command and enter the code as the password.
3. The Docker client creates a registry session that remains usable after the login code expires.

Treat the login code like a password. It is secret, can be used only once, and expires after a few
minutes.

A registry session belongs to your Hostly account, while access to repository content follows your
current workspace permissions. Hostly shows active sessions together with details such as their
creation date, last use, client, and IP address.

Revoke a session when you no longer use the client or do not recognize it. Revocation prevents that
session from renewing registry access; it does not delete images or affect other sessions.

## Storage and deletion

The registry overview shows how much registry storage the workspace uses and its current storage
limit. Images may share stored data, so the sizes shown for individual images or tags should not be
added together to calculate total usage.

Deletion has two different scopes:

| Action | Effect |
| --- | --- |
| Delete a tag | Removes that tag from the image. Other tags remain available. |
| Delete an image | Removes the image and all of its tags. |
| Revoke a session | Removes that client's registry access without deleting image content. |

Deleting an image or tag cannot be undone. Push the content again if it is needed later.

## Registry and deployment are separate

Pushing an image only stores it in the registry. It does not create a Hostly service and does not
update an existing service.

To run the image, copy its complete reference from the registry page and use that reference in a
deployment. The deployment determines the running service, its container port, domain, resources,
and runtime configuration.

## Related concepts

* [What is a Service?](./service.md)
* [Account and Workspace](./account-and-workspace.md)
* [Resource Usage and Limits](./resources-and-limits.md)