Support mounting volumes and init hooks via config

Add a per-container `volumes` list of Docker-style "host:container[:ro]"
bind specs, enabling arbitrary mounts such as Snowflake init hooks
(e.g. /etc/localstack/init/ready.d/). The persistence mount to
/var/lib/localstack is folded into this list; the legacy singular
`volume` field still works for backward compatibility.

Relative host sources resolve against the config file's directory and a
leading ~/ is expanded, since the Docker SDK treats a non-absolute
source as a named volume. Extra mounts must already exist (init-hook
entries are files), unlike the persistence dir which is created.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anisaoshafi

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`.
 
+## Volume Mounts
+
+Each `[[containers]]` block accepts a `volumes` list of Docker-style `"host:container[:ro]"` bind specs (e.g. for Snowflake init hooks mounted into `/etc/localstack/init/{boot,start,ready,shutdown}.d`). The persistence/cache mount to `/var/lib/localstack` is folded into this list: the entry whose container target is `/var/lib/localstack` (`persistenceTarget` in `internal/config/containers.go`) defines the host dir backing it, and that path is what `VolumeDir()`, `lstk volume path`, and `lstk volume clear` resolve. Resolution precedence in `VolumeDir()`: a `volumes` entry targeting `/var/lib/localstack` → the legacy singular `volume = "..."` field (still honored for backward compatibility) → the default OS cache dir. Setting the persistence dir via both `volume` and a `volumes` entry with differing sources is a validation error.
+
+Parsing/resolution lives in `parseVolume`/`ExtraVolumes` in `internal/config/containers.go`. Relative host sources resolve against the **config file's directory** and a leading `~/` is expanded — this is required because the Docker SDK treats a non-absolute source as a *named volume* rather than a bind mount. `start.go` mounts the persistence dir (creating it via `MkdirAll`) and appends `ExtraVolumes()`; extra sources are not created (`os.Stat` + error if missing) since init-hook entries are files, not dirs.
+
 # Emulator Setup Commands
 
 Use `lstk setup <emulator>` to set up CLI integration for an emulator type:

internal/config/containers.go

@@ -112,18 +112,147 @@ 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"`
+	// Volume is the legacy single-host-directory knob for the persistence mount
+	// (target /var/lib/localstack). It is still honored; new configs can express the
+	// same mount as a Volumes entry targeting persistenceTarget instead.
+	Volume string `mapstructure:"volume"`
+	// Volumes is the umbrella list of "host:container[:ro]" bind specs. It covers
+	// arbitrary mounts (e.g. Snowflake init hooks) and may also contain the persistence
+	// mount (the entry targeting /var/lib/localstack).
+	Volumes []string `mapstructure:"volumes"`
 	// Env is a list of named environment references defined in the top-level [env.*] config sections.
 	Env []string `mapstructure:"env"`
 }
 
-// VolumeDir returns the host directory to mount into the container for persistence/caching.
-// If Volume is set in the config, it is returned as-is. Otherwise, a default is computed
-// from os.UserCacheDir()/lstk/volume/<container-name>.
+// persistenceTarget is the container path of the managed persistence/cache mount.
+// The entry in Volumes targeting this path (or the legacy Volume field) defines the
+// host directory backing it; lstk creates it and `lstk volume clear`/`volume path` act on it.
+const persistenceTarget = "/var/lib/localstack"
+
+// VolumeMount is a parsed bind specification with the host source resolved to an absolute path.
+type VolumeMount struct {
+	Source   string
+	Target   string
+	ReadOnly bool
+}
+
+// parseVolume parses a "host:container[:opts]" spec. The host source is resolved to an
+// absolute path: a leading "~/" is expanded to the user's home directory, and a relative
+// path is joined with configDir (the directory of the config file that declared it). This
+// is required because the Docker SDK treats a non-absolute source as a named volume rather
+// than a bind mount. opts is a comma-separated list; only "ro" is honored.
+//
+// Note: a Windows drive-letter source (e.g. "C:\\data") splits on ":" ambiguously — the same
+// limitation as the upstream LocalStack volume parser.
+func parseVolume(spec, configDir string) (VolumeMount, error) {
+	parts := strings.Split(spec, ":")
+	if len(parts) < 2 || len(parts) > 3 {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: expected \"host:container\" or \"host:container:ro\"", spec)
+	}
+
+	source, target := parts[0], parts[1]
+	if source == "" {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: host source is empty", spec)
+	}
+	if target == "" {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: container target is empty", spec)
+	}
+	if !filepath.IsAbs(target) {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: container target %q must be an absolute path", spec, target)
+	}
+
+	resolved, err := resolveHostPath(source, configDir)
+	if err != nil {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: %w", spec, err)
+	}
+
+	var readOnly bool
+	if len(parts) == 3 {
+		for _, opt := range strings.Split(parts[2], ",") {
+			if opt == "ro" {
+				readOnly = true
+			}
+		}
+	}
+
+	return VolumeMount{Source: resolved, Target: target, ReadOnly: readOnly}, nil
+}
+
+// resolveHostPath expands a leading "~/" and makes a relative path absolute against configDir.
+func resolveHostPath(path, configDir string) (string, error) {
+	if path == "~" || strings.HasPrefix(path, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("failed to expand ~: %w", err)
+		}
+		path = filepath.Join(home, strings.TrimPrefix(path, "~"))
+	}
+	if filepath.IsAbs(path) {
+		return path, nil
+	}
+	return filepath.Join(configDir, path), nil
+}
+
+// configDirForRelativePaths returns the directory used to resolve relative volume sources:
+// the directory of the resolved config file. It falls back to the current working directory
+// when no config file is in use (e.g. in-memory defaults).
+func configDirForRelativePaths() string {
+	path, err := ConfigFilePath()
+	if err != nil || path == "" {
+		return "."
+	}
+	return filepath.Dir(path)
+}
+
+// parsedVolumes parses every entry in Volumes, resolving sources against the config dir.
+func (c *ContainerConfig) parsedVolumes() ([]VolumeMount, error) {
+	configDir := configDirForRelativePaths()
+	mounts := make([]VolumeMount, 0, len(c.Volumes))
+	for _, spec := range c.Volumes {
+		m, err := parseVolume(spec, configDir)
+		if err != nil {
+			return nil, err
+		}
+		mounts = append(mounts, m)
+	}
+	return mounts, nil
+}
+
+// ExtraVolumes returns the parsed bind mounts EXCLUDING the persistence entry
+// (target /var/lib/localstack), which start.go mounts separately via VolumeDir.
+func (c *ContainerConfig) ExtraVolumes() ([]VolumeMount, error) {
+	mounts, err := c.parsedVolumes()
+	if err != nil {
+		return nil, err
+	}
+	extras := make([]VolumeMount, 0, len(mounts))
+	for _, m := range mounts {
+		if m.Target == persistenceTarget {
+			continue
+		}
+		extras = append(extras, m)
+	}
+	return extras, nil
+}
+
+// VolumeDir returns the host directory to mount into the container for persistence/caching
+// (the mount targeting /var/lib/localstack). Resolution precedence:
+//  1. A Volumes entry targeting persistenceTarget — its resolved host source.
+//  2. The legacy Volume field, if set — returned as-is.
+//  3. The default os.UserCacheDir()/lstk/volume/<container-name>.
 func (c *ContainerConfig) VolumeDir() (string, error) {
+	mounts, err := c.parsedVolumes()
+	if err != nil {
+		return "", err
+	}
+	for _, m := range mounts {
+		if m.Target == persistenceTarget {
+			return m.Source, nil
+		}
+	}
 	if c.Volume != "" {
 		return c.Volume, nil
 	}
@@ -182,6 +311,33 @@ func (c *ContainerConfig) Validate() error {
 	if port < 1 || port > 65535 {
 		return fmt.Errorf("port %d is out of range (must be 1–65535)", port)
 	}
+	return c.validateVolumes()
+}
+
+// validateVolumes checks each Volumes entry is structurally parseable and guards against
+// declaring the persistence directory twice with conflicting sources. It does not touch the
+// filesystem (existence of sources is checked at start time).
+func (c *ContainerConfig) validateVolumes() error {
+	configDir := configDirForRelativePaths()
+	var persistenceSource string
+	for _, spec := range c.Volumes {
+		m, err := parseVolume(spec, configDir)
+		if err != nil {
+			return err
+		}
+		if m.Target == persistenceTarget {
+			persistenceSource = m.Source
+		}
+	}
+	if c.Volume != "" && persistenceSource != "" {
+		resolved, err := resolveHostPath(c.Volume, configDir)
+		if err != nil {
+			return err
+		}
+		if resolved != persistenceSource {
+			return fmt.Errorf("persistence directory set both via 'volume' and a 'volumes' entry targeting %s; use one or the other", persistenceTarget)
+		}
+	}
 	return nil
 }
 

internal/config/containers_test.go

@@ -1,6 +1,8 @@
 package config
 
 import (
+	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"testing"
@@ -80,12 +82,12 @@ func TestNormalizeTag(t *testing.T) {
 
 func TestValidate_InvalidDockerTag_IsRejected(t *testing.T) {
 	for _, tag := range []string{
-		"my tag",   // space
-		"2026.4!",  // special char
-		".hidden",  // starts with dot
-		"-beta",    // starts with hyphen
-		"tag@sha",  // @ not allowed
-		"foo:bar",  // colon not allowed
+		"my tag",                 // space
+		"2026.4!",                // special char
+		".hidden",                // starts with dot
+		"-beta",                  // starts with hyphen
+		"tag@sha",                // @ not allowed
+		"foo:bar",                // colon not allowed
 		strings.Repeat("a", 129), // too long
 	} {
 		t.Run(tag, func(t *testing.T) {
@@ -185,3 +187,129 @@ func TestValidate_NegativePort(t *testing.T) {
 	err := c.Validate()
 	assert.ErrorContains(t, err, "out of range")
 }
+
+func TestParseVolume_TwoParts(t *testing.T) {
+	m, err := parseVolume("/host/data:/var/lib/localstack", "/cfg")
+	require.NoError(t, err)
+	assert.Equal(t, VolumeMount{Source: "/host/data", Target: "/var/lib/localstack", ReadOnly: false}, m)
+}
+
+func TestParseVolume_ReadOnly(t *testing.T) {
+	m, err := parseVolume("/host/seed:/seed:ro", "/cfg")
+	require.NoError(t, err)
+	assert.Equal(t, VolumeMount{Source: "/host/seed", Target: "/seed", ReadOnly: true}, m)
+}
+
+func TestParseVolume_ReadOnlyAmongOptions(t *testing.T) {
+	m, err := parseVolume("/host/seed:/seed:z,ro", "/cfg")
+	require.NoError(t, err)
+	assert.True(t, m.ReadOnly)
+}
+
+func TestParseVolume_RelativeSourceResolvedAgainstConfigDir(t *testing.T) {
+	m, err := parseVolume("./init.sf.sql:/etc/localstack/init/ready.d/init.sf.sql", "/cfg/project")
+	require.NoError(t, err)
+	assert.Equal(t, "/cfg/project/init.sf.sql", m.Source)
+}
+
+func TestParseVolume_TildeExpanded(t *testing.T) {
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+	m, err := parseVolume("~/scripts/x.sf.sql:/etc/localstack/init/ready.d/x.sf.sql", "/cfg")
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(home, "scripts/x.sf.sql"), m.Source)
+}
+
+func TestParseVolume_AbsoluteSourceUnchanged(t *testing.T) {
+	m, err := parseVolume("/abs/x.sf.sql:/etc/localstack/init/ready.d/x.sf.sql", "/cfg")
+	require.NoError(t, err)
+	assert.Equal(t, "/abs/x.sf.sql", m.Source)
+}
+
+func TestParseVolume_Errors(t *testing.T) {
+	cases := map[string]string{
+		"one part":        "/host/only",
+		"four parts":      "/h:/c:ro:extra",
+		"empty source":    ":/c",
+		"empty target":    "/h:",
+		"relative target": "/h:relative/target",
+	}
+	for name, spec := range cases {
+		t.Run(name, func(t *testing.T) {
+			_, err := parseVolume(spec, "/cfg")
+			assert.Error(t, err)
+		})
+	}
+}
+
+func TestVolumeDir_VolumesEntryTargetingPersistenceWins(t *testing.T) {
+	c := &ContainerConfig{
+		Type:    EmulatorAWS,
+		Volume:  "", // not set
+		Volumes: []string{"/persist/dir:/var/lib/localstack", "/abs/x.sf.sql:/etc/localstack/init/ready.d/x.sf.sql"},
+	}
+	dir, err := c.VolumeDir()
+	require.NoError(t, err)
+	assert.Equal(t, "/persist/dir", dir)
+}
+
+func TestVolumeDir_LegacyVolumeUsedWhenNoPersistenceEntry(t *testing.T) {
+	c := &ContainerConfig{
+		Type:    EmulatorAWS,
+		Volume:  "/legacy/persist",
+		Volumes: []string{"/abs/x.sf.sql:/etc/localstack/init/ready.d/x.sf.sql"},
+	}
+	dir, err := c.VolumeDir()
+	require.NoError(t, err)
+	assert.Equal(t, "/legacy/persist", dir)
+}
+
+func TestVolumeDir_DefaultsToCacheDirWhenNeitherSet(t *testing.T) {
+	cacheDir, err := os.UserCacheDir()
+	require.NoError(t, err)
+	c := &ContainerConfig{Type: EmulatorAWS}
+	dir, err := c.VolumeDir()
+	require.NoError(t, err)
+	assert.Equal(t, filepath.Join(cacheDir, "lstk", "volume", c.Name()), dir)
+}
+
+func TestExtraVolumes_ExcludesPersistenceEntry(t *testing.T) {
+	c := &ContainerConfig{
+		Type: EmulatorAWS,
+		Volumes: []string{
+			"/persist/dir:/var/lib/localstack",
+			"/abs/a.sf.sql:/etc/localstack/init/ready.d/a.sf.sql",
+			"/abs/b.sf.sql:/etc/localstack/init/ready.d/b.sf.sql:ro",
+		},
+	}
+	extras, err := c.ExtraVolumes()
+	require.NoError(t, err)
+	require.Len(t, extras, 2)
+	assert.Equal(t, VolumeMount{Source: "/abs/a.sf.sql", Target: "/etc/localstack/init/ready.d/a.sf.sql"}, extras[0])
+	assert.Equal(t, VolumeMount{Source: "/abs/b.sf.sql", Target: "/etc/localstack/init/ready.d/b.sf.sql", ReadOnly: true}, extras[1])
+}
+
+func TestValidate_RejectsMalformedVolume(t *testing.T) {
+	c := &ContainerConfig{Type: EmulatorAWS, Port: "4566", Volumes: []string{"/host/only"}}
+	assert.ErrorContains(t, c.Validate(), "invalid volume")
+}
+
+func TestValidate_RejectsConflictingPersistenceSources(t *testing.T) {
+	c := &ContainerConfig{
+		Type:    EmulatorAWS,
+		Port:    "4566",
+		Volume:  "/persist/a",
+		Volumes: []string{"/persist/b:/var/lib/localstack"},
+	}
+	assert.ErrorContains(t, c.Validate(), "persistence directory set both")
+}
+
+func TestValidate_AllowsMatchingPersistenceSources(t *testing.T) {
+	c := &ContainerConfig{
+		Type:    EmulatorAWS,
+		Port:    "4566",
+		Volume:  "/persist/same",
+		Volumes: []string{"/persist/same:/var/lib/localstack"},
+	}
+	assert.NoError(t, c.Validate())
+}

internal/config/default_config.toml

@@ -11,6 +11,14 @@ tag  = "latest"  # Docker image tag, e.g. "latest", "2026.4"
 port = "4566"    # Host port the emulator will be accessible on
 # volume = ""    # Host directory for persistent state (default: OS cache dir)
 # env = []       # Named environment profiles to apply (see [env.*] sections below)
+# volumes = []   # Extra bind mounts, each "host:container[:ro]". Relative host paths
+#                # resolve against this config file's directory; a leading ~/ is expanded.
+#                # A "volumes" entry targeting /var/lib/localstack sets the persistent
+#                # state directory (equivalent to "volume" above).
+#                #
+#                # Mount Snowflake init hooks (scripts run on startup) — see
+#                # https://docs.localstack.cloud/snowflake/capabilities/init-hooks/
+#                # volumes = ["./test.sf.sql:/etc/localstack/init/ready.d/test.sf.sql"]
 
 # Environment profiles let you group environment variables and reference
 # them by name in one or more containers via the 'env' field above.

internal/container/start.go

@@ -139,6 +139,20 @@ func Start(ctx context.Context, rt runtime.Runtime, sink output.Sink, opts Start
 		}
 		binds = append(binds, runtime.BindMount{HostPath: volumeDir, ContainerPath: "/var/lib/localstack"})
 
+		// Extra user-defined mounts (e.g. Snowflake init hooks). Unlike the persistence
+		// directory, these are not created — init-hook entries are files, so the source
+		// must already exist; creating it would produce a wrong empty directory.
+		extraVolumes, err := c.ExtraVolumes()
+		if err != nil {
+			return "", err
+		}
+		for _, m := range extraVolumes {
+			if _, err := os.Stat(m.Source); err != nil {
+				return "", fmt.Errorf("volume source %q does not exist: %w", m.Source, err)
+			}
+			binds = append(binds, runtime.BindMount{HostPath: m.Source, ContainerPath: m.Target, ReadOnly: m.ReadOnly})
+		}
+
 		containers[i] = runtime.ContainerConfig{
 			Image:         image,
 			Name:          containerName,