feat: support offline mode and custom images for enterprise setups

Enterprise environments that cannot pull from Docker Hub (internal
registries, offline/air-gapped, proxy/cert issues) now have two
complementary knobs, following Carole's proposal:

- A per-container `image` config field overrides the default Docker Hub
  image (e.g. an internal-registry mirror or a locally loaded image). If
  it carries no tag, the configured `tag` (or "latest") is appended.
- `lstk --offline` (or `LSTK_OFFLINE=1`) runs from a locally available
  image without pulling, skips the license-server check (the license
  ships inside enterprise images), makes the auth token optional, and
  disables telemetry and update checks.

In offline mode `container.Start` uses `useLocalImages`, which verifies
the image is present locally via the new `runtime.ImageExists` and emits
an actionable error if it is missing, instead of pulling and validating.

Generated with [Linear](https://linear.app/localstack/issue/DEVX-703/support-enterprise-environments-that-cannot-pull-from-docker-hub#agent-session-77e3f9fc)

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>

Author: gtsiolis

CLAUDE.md

@@ -66,6 +66,12 @@ When adding a new command that depends on configuration, wire config initializat
 
 Created automatically on first run with defaults. Supports emulator types: `aws`, `snowflake`, and `azure`.
 
+Each `[[containers]]` block may set an optional `image` to override the default Docker Hub image (e.g. an internal registry mirror or a locally loaded offline image). `ContainerConfig.Image()` returns `image` as-is when it already carries a tag, otherwise it appends `tag` (or `latest`); the default `localstack/<product>:<tag>` is used when `image` is unset.
+
+# Offline Mode
+
+For enterprise environments that cannot pull from Docker Hub, `lstk --offline` (or `LSTK_OFFLINE=1`) runs the emulator from a locally available image without pulling, skips the license-server check (the license ships inside enterprise images), and disables telemetry/update checks. The flag is a persistent root flag honored by `start` and `restart`; `cmd.resolveOfflineFlag` folds it into `env.Env.Offline`, which flows into `container.StartOptions.Offline`. In offline mode `container.Start` calls `useLocalImages` (verifies the image exists locally via `runtime.ImageExists`, no pull, no license validation) instead of the pull/validate path, and an auth token becomes optional. Pair it with a custom `image` in the config to point at a locally loaded or internal-registry image.
+
 # Emulator Setup Commands
 
 Use `lstk setup <emulator>` to set up CLI integration for an emulator type:

cmd/restart.go

@@ -37,6 +37,13 @@ func newRestartCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobr
 				return err
 			}
 
+			if err := resolveOfflineFlag(cmd, cfg); err != nil {
+				return err
+			}
+			if cfg.Offline {
+				tel.Disable()
+			}
+
 			stopOpts := container.StopOptions{
 				Telemetry: tel,
 			}

cmd/root.go

@@ -50,6 +50,9 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 			if err != nil {
 				return err
 			}
+			if err := resolveOfflineFlag(cmd, cfg); err != nil {
+				return err
+			}
 			return startEmulator(cmd.Context(), rt, cfg, tel, logger, persist, firstRun)
 		},
 	}
@@ -60,6 +63,7 @@ func NewRootCmd(cfg *env.Env, tel *telemetry.Client, logger log.Logger) *cobra.C
 
 	root.PersistentFlags().String("config", "", "Path to config file")
 	root.PersistentFlags().BoolVar(&cfg.NonInteractive, "non-interactive", false, "Disable interactive mode")
+	root.PersistentFlags().Bool("offline", false, "Run from a locally available image without pulling or contacting the license server")
 	root.Flags().Bool("persist", false, "Persist emulator state across restarts")
 
 	configureHelp(root)
@@ -157,6 +161,17 @@ func Execute(ctx context.Context) error {
 	return nil
 }
 
+// resolveOfflineFlag folds the --offline flag into cfg.Offline (which may already
+// be set via LSTK_OFFLINE) so both the env var and the flag enable offline mode.
+func resolveOfflineFlag(cmd *cobra.Command, cfg *env.Env) error {
+	offline, err := cmd.Flags().GetBool("offline")
+	if err != nil {
+		return err
+	}
+	cfg.Offline = cfg.Offline || offline
+	return nil
+}
+
 func buildStartOptions(cfg *env.Env, appConfig *config.Config, logger log.Logger, tel *telemetry.Client, persist bool) container.StartOptions {
 	return container.StartOptions{
 		PlatformClient:   api.NewPlatformClient(cfg.APIEndpoint, logger),
@@ -169,6 +184,7 @@ func buildStartOptions(cfg *env.Env, appConfig *config.Config, logger log.Logger
 		Persist:          persist,
 		Logger:           logger,
 		Telemetry:        tel,
+		Offline:          cfg.Offline,
 	}
 }
 
@@ -178,6 +194,12 @@ func startEmulator(ctx context.Context, rt runtime.Runtime, cfg *env.Env, tel *t
 		return fmt.Errorf("failed to get config: %w", err)
 	}
 
+	// Offline environments may not be able to reach the analytics endpoint, so
+	// disable telemetry entirely rather than queue events that can never flush.
+	if cfg.Offline {
+		tel.Disable()
+	}
+
 	opts := buildStartOptions(cfg, appConfig, logger, tel, persist)
 
 	notifyOpts := update.NotifyOptions{
@@ -212,7 +234,9 @@ func startEmulator(ctx context.Context, rt runtime.Runtime, cfg *env.Env, tel *t
 			Text:     fmt.Sprintf("Configured with default emulator %s.", emName),
 		})
 	}
-	update.NotifyUpdate(ctx, sink, update.NotifyOptions{GitHubToken: cfg.GitHubToken})
+	if !cfg.Offline {
+		update.NotifyUpdate(ctx, sink, update.NotifyOptions{GitHubToken: cfg.GitHubToken})
+	}
 	if _, err = container.Start(ctx, rt, sink, opts, false); err != nil {
 		return err
 	}

cmd/start.go

@@ -26,6 +26,9 @@ Host environment variables prefixed with LOCALSTACK_ are forwarded to the emulat
 			if err != nil {
 				return err
 			}
+			if err := resolveOfflineFlag(c, cfg); err != nil {
+				return err
+			}
 			return startEmulator(c.Context(), rt, cfg, tel, logger, persist, firstRun)
 		},
 	}

internal/config/containers.go

@@ -112,10 +112,15 @@ func KnownImageReposForType(t EmulatorType) []string {
 }
 
 type ContainerConfig struct {
-	Type   EmulatorType `mapstructure:"type"`
-	Tag    string       `mapstructure:"tag"`
-	Port   string       `mapstructure:"port"`
-	Volume string       `mapstructure:"volume"`
+	Type EmulatorType `mapstructure:"type"`
+	Tag  string       `mapstructure:"tag"`
+	Port string       `mapstructure:"port"`
+	// CustomImage overrides the default Docker image for this emulator. Set it to use an
+	// image from an internal registry or a locally loaded offline image instead of pulling
+	// the default localstack image from Docker Hub. If it carries no tag, Tag (or "latest")
+	// is appended.
+	CustomImage string `mapstructure:"image"`
+	Volume      string `mapstructure:"volume"`
 	// Env is a list of named environment references defined in the top-level [env.*] config sections.
 	Env []string `mapstructure:"env"`
 }
@@ -202,17 +207,32 @@ func (c *ContainerConfig) ResolvedEnv(namedEnvs map[string]map[string]string) ([
 }
 
 func (c *ContainerConfig) Image() (string, error) {
-	productName, err := c.ProductName()
-	if err != nil {
-		return "", err
-	}
 	tag := c.Tag
 	if tag == "" {
 		tag = "latest"
 	}
+	if c.CustomImage != "" {
+		if imageHasTag(c.CustomImage) {
+			return c.CustomImage, nil
+		}
+		return c.CustomImage + ":" + tag, nil
+	}
+	productName, err := c.ProductName()
+	if err != nil {
+		return "", err
+	}
 	return fmt.Sprintf("%s/%s:%s", dockerRegistry, productName, tag), nil
 }
 
+// imageHasTag reports whether a Docker image reference already includes a tag.
+// A colon only counts as a tag separator when it appears in the final path
+// segment, so "my-registry:5000/localstack-pro" (registry port, no tag) is
+// correctly treated as untagged.
+func imageHasTag(image string) bool {
+	lastSegment := image[strings.LastIndex(image, "/")+1:]
+	return strings.Contains(lastSegment, ":")
+}
+
 // Name returns the container name: "localstack-{type}" or "localstack-{type}-{tag}" if tag != latest
 func (c *ContainerConfig) Name() string {
 	tag := c.Tag

internal/config/containers_test.go

@@ -140,6 +140,36 @@ func TestEmulatorTypeForImage_Azure(t *testing.T) {
 	assert.Equal(t, EmulatorAzure, EmulatorTypeForImage("localstack/localstack-azure:latest"))
 }
 
+func TestImage_CustomImage(t *testing.T) {
+	tests := []struct {
+		name        string
+		customImage string
+		tag         string
+		want        string
+	}{
+		{"untagged custom image gets configured tag", "my-registry.internal/localstack-pro", "2026.4", "my-registry.internal/localstack-pro:2026.4"},
+		{"untagged custom image defaults to latest", "local-image-name", "", "local-image-name:latest"},
+		{"tagged custom image is used as-is", "my-registry.internal/localstack-pro:custom", "latest", "my-registry.internal/localstack-pro:custom"},
+		{"registry port is not mistaken for a tag", "my-registry:5000/localstack-pro", "2026.4", "my-registry:5000/localstack-pro:2026.4"},
+		{"registry port with explicit tag", "my-registry:5000/localstack-pro:custom", "", "my-registry:5000/localstack-pro:custom"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := &ContainerConfig{Type: EmulatorAWS, Port: "4566", Tag: tt.tag, CustomImage: tt.customImage}
+			image, err := c.Image()
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, image)
+		})
+	}
+}
+
+func TestImage_DefaultWhenNoCustomImage(t *testing.T) {
+	c := &ContainerConfig{Type: EmulatorAWS, Port: "4566", Tag: "latest"}
+	image, err := c.Image()
+	require.NoError(t, err)
+	assert.Equal(t, "localstack/localstack-pro:latest", image)
+}
+
 func TestSelfValidatesLicense(t *testing.T) {
 	// Snowflake and Azure containers activate their own license against the
 	// licensing server, so lstk skips its pre-flight platform license check.

internal/config/default_config.toml

@@ -9,9 +9,16 @@
 type = "aws"     # Emulator type. Currently supported: "aws", "snowflake", "azure"
 tag  = "latest"  # Docker image tag, e.g. "latest", "2026.4"
 port = "4566"    # Host port the emulator will be accessible on
+# image = ""     # Custom image to use instead of the default Docker Hub image, e.g.
+#                # an internal registry mirror or a locally loaded offline image.
+#                # If it carries no tag, 'tag' above is appended.
 # volume = ""    # Host directory for persistent state (default: OS cache dir)
 # env = []       # Named environment profiles to apply (see [env.*] sections below)
 
+# Run 'lstk --offline' (or set LSTK_OFFLINE=1) in environments that cannot pull
+# from Docker Hub. Offline mode uses the local image without pulling, skips the
+# license check (the license ships inside enterprise images), and disables telemetry.
+
 # Environment profiles let you group environment variables and reference
 # them by name in one or more containers via the 'env' field above.
 #