[FEAT] [CLI] Make Hatchet Lite version configurable

[gregfurman]

Is your feature request related to a problem? Please describe.

When running hatchet server start, we hardcode this to always pull the latest image of hatchet-lite

hatchet/cmd/hatchet-cli/cli/internal/drivers/docker/hatchet_lite.go

Lines 358 to 365 in df93e74

	func (d *DockerDriver) startHatchetLiteContainer(ctx context.Context, opts *HatchetLiteOpts, networkId string, dashboardPort, grpcPort int, sharedLabels map[string]string) error {
	imageName := "ghcr.io/hatchet-dev/hatchet/hatchet-lite:latest"
	containerName := canonicalContainerName(opts.projectName, opts.hatchetName)
	out, err := d.apiClient.ImagePull(ctx, imageName, image.PullOptions{})
	if err != nil {
	return fmt.Errorf("could not pull image %s: %w", imageName, err)
	}

While ensuring that the latest version of hatchet lite (and therefore the engine and api server) is always pulled and run, the approach has several issues:

1. Airgapped environments (i.e without access to ghcr.io) cannot take advantage of pre-existing hatchet-lite images already available.

2. Forced upgrades to a later version of hatchet occur regardless of whether current infrastructure/application logic caters for this. For example, what if I am running an older version of the SDK with functionality that has been removed in the latest version of hatchet?

3. A supply chain attack means a malicious version getting published will automatically be pulled in by all users starting a hatchet instance via hatchet server start

Describe the solution you'd like

Allow the hatchet version to be overridable via config or a flag i.e

hatchet server --tag v0.83.1 start

In addition, we could include a flag to skip an ImagePull call. I think it'd be easiest to align this approach with docker compose's pull_policy (see https://docs.docker.com/reference/compose-file/services/#pull_policy) (i.e always, never, missing)

hatchet server --pull-policy "missing" start

Or perhaps prompt a user to agree that a new version of hatchet is going to be pulled in.

Describe alternatives you've considered

This can be worked around with docker compose and specifying the exact image we want to use, but that defeats the purpose of the (more convienient) hatchet CLI on offer.

Additional context
N/A

[Ujjwal-Singh-20]

Hey @gregfurman,
I added two new flags to hatchet server start: --tag (default "latest") to let users pin a specific hatchet-lite image version (e.g. --tag v0.83.1), and --pull-policy (default "always") which accepts "always", "missing", or "never" - aligned with Docker Compose pull_policy semantics.

The core change is a new pullImageWithPolicy() method in the Docker driver that replaces the two hardcoded ImagePull calls. With "never" it skips the pull entirely and errors if the image isnt local, with "missing" it checks ImageInspect first and only pulls if needed, and "always" preserves existing behavior. The hatchet-lite image name is now built dynamically from the tag instead of being hardcoded to :latest. All existing defaults are preserved so this is fully backwards-compatible.

Tested locally, build passes, --tag v0.83.1 correctly pulls and starts the pinned version, --pull-policy never fails cleanly when the image isnt local, and invalid policies are rejected with a clear error message.

Ready to open a PR or make adjustments if the approach is ok

[abelanger5]

Hi @Ujjwal-Singh-20 and @gregfurman ; related but perhaps a separate issue, we should definitely support setting env vars which are passed into the hatchet-lite container on the server start command. For example, toggling SERVER_OBSERVABILITY_ENABLED would be extremely useful.

[Ujjwal-Singh-20]

Hi @abelanger5 , thats a great suggestion, i guess that will be handled in a new issue,
@gregfurman,
saw the 👀 reaction, sorry, I didnt quite catch the meaning of it. Could you clarify if the approach looks good to you, or if you would like any changes?

[gregfurman]

@abelanger5 nice idea! The LocalStack CLI would assume any environment variable prefixed with LOCALSTACK_ should be propagated to the container at startup. Perhaps we can do the same for the hatchet CLI? Also, adding support for passing select environment variables in the same way the docker CLI does it i.e with -e/--env.

So this could look like:

HATCHET_BAR="bar" hatchet server -e FOO="foo" start 

where HATCHET_BAR and FOO are passed into the container.

[gregfurman]

@Ujjwal-Singh-20 The 👀 means I'm currently looking at your comment 🙂

Ready to open a PR or make adjustments if the approach is ok

Approach LGTM. Looking forward to reviewing it!

[Ujjwal-Singh-20]

@Ujjwal-Singh-20 The 👀 means I'm currently looking at your comment 🙂

Understood, thanks for the clarification
Opening the PR