Skip to main content
Images are filesystem snapshots. Every non-disposable contree run produces a new image. Tags give images human-readable names so you can find and reuse them later. All data — images, operations, and uploaded files — is scoped to a Project. Multiple tokens can access the same project and share its data. Different projects have separate scopes — nothing is visible across project boundaries.

​
Listing images

Show tagged images:
Filter by tag prefix:
Include untagged images:
Filter by time:

​
Tagging images

With one argument, tags the current session image. With two, the first is the image reference:
The CLI resolves tag references to UUIDs automatically — you don’t need to look up the UUID first. Tags follow a free-form name:version convention. Common patterns:
Remove a tag:

​
Tag rules

  • Tags are scoped to your Project (API token)
  • Each image can have multiple tags
  • Tags are unique — assigning an existing tag to a different image moves it
  • Allowed characters: a-z, 0-9, _, -, with :, /, . as separators
  • Max length: 256 characters
  • Case-sensitive (lowercase recommended)

​
Shadow behavior

Public images (like ubuntu:latest) have their own tags. When you assign the same tag to your own image, the public image is still accessible by UUID but its tag becomes shadowed. Removing your tag restores the public one.

​
Using tags

Use tag:NAME anywhere an image UUID is expected:
If both you and a public image share a tag, your image wins.

​
Importing images

Pull images from container registries (Docker Hub, GHCR, etc.):
Import is asynchronous — the CLI polls until the operation completes. Press Ctrl+C to cancel. Import multiple at once:

​
Private registries

Authenticate with --username:
The password is prompted securely if --username is provided. Credentials are used only for the import operation and discarded immediately after — the server does not store them.

​
Reusing images across sessions

A common workflow is to prepare a base environment, tag it, and reuse it in future sessions:
Search for existing tagged images before rebuilding:
Images are your checkpoints. Next: Building from a Dockerfile.