Support mounting volumes and init hooks via config

Author: anisaoshafi

README.md

@@ -122,17 +122,40 @@ lstk --config /path/to/config.toml start
 type = "aws"     # Emulator type. Currently supported: "aws", "snowflake", "azure"
 tag  = "latest"  # Docker image tag, e.g. "latest", "2026.03"
 port = "4566"    # Host port the emulator will be accessible on
-# volume = ""    # Host directory for persistent state (default: OS cache dir)
+# volumes = []   # Bind mounts as "host:container[:ro]" (see "Mounting volumes and init hooks")
 # env = []       # Named environment profiles to apply (see [env.*] sections below)
 ```
 
 **Fields:**
 - `type`: emulator type; one of `"aws"`, `"snowflake"`, or `"azure"`
 - `tag`: Docker image tag for LocalStack (e.g. `"latest"`, `"4.14.0"`); useful for pinning a version
 - `port`: port LocalStack listens on (default `4566`)
-- `volume`: (optional) host directory for persistent emulator state (default: OS cache dir)
+- `volumes`: (optional) bind mounts in `"host:container[:ro]"` form — for init hooks, or to set the persistence directory by mounting to `/var/lib/localstack` (see below); `volume` is an accepted alias
 - `env`: (optional) list of named environment variable groups to inject into the container (see below)
 
+### Mounting volumes and init hooks
+
+Use `volumes` to mount host files or directories into the emulator. Each entry is a docker-style `"host:container"` (add `:ro` for read-only). Relative paths and a leading `~` are resolved automatically. `volume` and `volumes` are interchangeable aliases — both take the same list and their entries are combined. A bare host path with no container part (e.g. `volume = "/my/data"`) is mounted as the persistence directory, which keeps the legacy single-string form working.
+
+A common use is [init hooks](https://docs.localstack.cloud/snowflake/capabilities/init-hooks/) — scripts the emulator runs on startup. Mount them into one of `/etc/localstack/init/{boot,start,ready,shutdown}.d`. For example, to seed Snowflake data once the emulator is ready:
+
+```toml
+[[containers]]
+type = "snowflake"
+port = "4566"
+volumes = ["./init:/etc/localstack/init/ready.d:ro"]
+```
+
+Any `*.sf.sql` file in `./init` then runs automatically when the emulator is ready.
+
+The emulator's persistent state lives at `/var/lib/localstack`. By default lstk mounts a directory under your OS cache dir there; mount your own host directory to that path to control where state is stored:
+
+```toml
+volumes = ["/my/data:/var/lib/localstack"]
+```
+
+`lstk volume path` prints this directory and `lstk volume clear` empties it.
+
 ### Passing environment variables to the container
 
 Define reusable named env sets and reference them per container:

internal/config/containers.go

@@ -20,6 +20,11 @@ const (
 
 	DefaultPort    = "4566"
 	dockerRegistry = "localstack"
+
+	// PersistenceContainerPath is the container path holding the emulator's
+	// persistent state. The volumes entry targeting it is the persistence mount;
+	// if none does, lstk mounts a default host directory there.
+	PersistenceContainerPath = "/var/lib/localstack"
 )
 
 var emulatorDisplayNames = map[EmulatorType]string{
@@ -112,20 +117,150 @@ 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"`
+	// Volumes is a list of bind mounts in "host:container[:ro|:rw]" form,
+	// e.g. "/home/me/init:/etc/localstack/init/ready.d:ro". This is how init hooks
+	// are mounted. The entry whose container path is PersistenceContainerPath
+	// ("/var/lib/localstack") holds the emulator's persistent state; if no entry
+	// targets it, lstk mounts a default host directory under the OS cache dir there.
+	Volumes []string `mapstructure:"volumes"`
+	// Volume is an accepted alias for Volumes; entries from both are combined.
+	Volume []string `mapstructure:"volume"`
 	// 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>.
+// VolumeSpecs returns the combined bind-mount specs from the Volumes and Volume
+// fields, which are interchangeable aliases.
+func (c *ContainerConfig) VolumeSpecs() []string {
+	specs := make([]string, 0, len(c.Volumes)+len(c.Volume))
+	specs = append(specs, c.Volumes...)
+	specs = append(specs, c.Volume...)
+	return specs
+}
+
+// VolumeMount is a parsed bind mount from the Volumes config field. It mirrors
+// runtime.BindMount but lives in config to avoid a dependency from config on the
+// runtime package; the container start path converts these into runtime.BindMount.
+type VolumeMount struct {
+	HostPath      string
+	ContainerPath string
+	ReadOnly      bool
+}
+
+// windowsDrivePathRe matches a leading Windows drive prefix like "C:\" or "c:/"
+// so the host:container split does not treat the drive-letter colon as a separator.
+var windowsDrivePathRe = regexp.MustCompile(`^[A-Za-z]:[\\/]`)
+
+// ParsedVolumes parses the combined Volumes/Volume config entries into VolumeMounts.
+// Each entry is "host:container" or "host:container:ro" (":rw" is also accepted and
+// means read-write). A bare "host" with no container part is mounted at the
+// persistence path (the legacy `volume = "/my/data"` form). Relative host paths are
+// made absolute and a leading "~" is expanded. The container path must be absolute.
+func (c *ContainerConfig) ParsedVolumes() ([]VolumeMount, error) {
+	var mounts []VolumeMount
+	for _, raw := range c.VolumeSpecs() {
+		m, err := parseVolume(raw)
+		if err != nil {
+			return nil, err
+		}
+		mounts = append(mounts, m)
+	}
+	return mounts, nil
+}
+
+func parseVolume(raw string) (VolumeMount, error) {
+	invalid := func() (VolumeMount, error) {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: expected \"host\" or \"host:container[:ro]\"", raw)
+	}
+
+	spec := raw
+	readOnly := false
+	// Strip an optional trailing mode (":ro" / ":rw"). Any other trailing
+	// token after the final colon is left as part of the container path.
+	if idx := strings.LastIndex(spec, ":"); idx != -1 {
+		switch spec[idx+1:] {
+		case "ro":
+			readOnly = true
+			spec = spec[:idx]
+		case "rw":
+			spec = spec[:idx]
+		}
+	}
+
+	// Split host:container on the first colon, skipping a Windows drive prefix.
+	searchFrom := 0
+	if windowsDrivePathRe.MatchString(spec) {
+		searchFrom = 2
+	}
+	idx := strings.Index(spec[searchFrom:], ":")
+
+	// No host:container separator: treat the whole spec as a host path mounted at
+	// the persistence path. This supports the legacy form `volume = "/my/data"`.
+	if idx == -1 {
+		if spec == "" {
+			return invalid()
+		}
+		host, err := resolveHostPath(spec)
+		if err != nil {
+			return VolumeMount{}, fmt.Errorf("invalid volume %q: %w", raw, err)
+		}
+		return VolumeMount{HostPath: host, ContainerPath: PersistenceContainerPath, ReadOnly: readOnly}, nil
+	}
+	idx += searchFrom
+
+	host := spec[:idx]
+	container := spec[idx+1:]
+	if host == "" || container == "" {
+		return invalid()
+	}
+	if !strings.HasPrefix(container, "/") && !windowsDrivePathRe.MatchString(container) {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: container path %q must be absolute", raw, container)
+	}
+
+	host, err := resolveHostPath(host)
+	if err != nil {
+		return VolumeMount{}, fmt.Errorf("invalid volume %q: %w", raw, err)
+	}
+
+	return VolumeMount{HostPath: host, ContainerPath: container, ReadOnly: readOnly}, nil
+}
+
+func resolveHostPath(host string) (string, error) {
+	if host == "~" || strings.HasPrefix(host, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("failed to expand \"~\": %w", err)
+		}
+		host = filepath.Join(home, strings.TrimPrefix(host, "~"))
+	}
+	// A Windows drive-absolute path (e.g. "C:\data") is already absolute; leave it
+	// as-is so parsing is host-OS-independent (filepath.Abs on non-Windows would
+	// wrongly treat it as relative and prepend the working directory).
+	if windowsDrivePathRe.MatchString(host) {
+		return host, nil
+	}
+	abs, err := filepath.Abs(host)
+	if err != nil {
+		return "", fmt.Errorf("failed to resolve host path %q: %w", host, err)
+	}
+	return abs, nil
+}
+
+// VolumeDir returns the host directory mounted for the emulator's persistent state
+// (at PersistenceContainerPath). If a volumes entry targets that path, its host side
+// is returned; otherwise a default is computed from os.UserCacheDir()/lstk/volume/<container-name>.
 func (c *ContainerConfig) VolumeDir() (string, error) {
-	if c.Volume != "" {
-		return c.Volume, nil
+	mounts, err := c.ParsedVolumes()
+	if err != nil {
+		return "", err
+	}
+	for _, m := range mounts {
+		if m.ContainerPath == PersistenceContainerPath {
+			return m.HostPath, nil
+		}
 	}
 	cacheDir, err := os.UserCacheDir()
 	if err != nil {
@@ -182,6 +317,9 @@ func (c *ContainerConfig) Validate() error {
 	if port < 1 || port > 65535 {
 		return fmt.Errorf("port %d is out of range (must be 1–65535)", port)
 	}
+	if _, err := c.ParsedVolumes(); err != nil {
+		return err
+	}
 	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,104 @@ func TestValidate_NegativePort(t *testing.T) {
 	err := c.Validate()
 	assert.ErrorContains(t, err, "out of range")
 }
+
+func TestParsedVolumes_BasicAndReadOnly(t *testing.T) {
+	c := &ContainerConfig{Volumes: []string{
+		"/host/data:/data",
+		"/host/init:/etc/localstack/init/ready.d:ro",
+		"/host/rw:/rw:rw",
+	}}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 3)
+
+	assert.Equal(t, VolumeMount{HostPath: "/host/data", ContainerPath: "/data", ReadOnly: false}, mounts[0])
+	assert.Equal(t, VolumeMount{HostPath: "/host/init", ContainerPath: "/etc/localstack/init/ready.d", ReadOnly: true}, mounts[1])
+	assert.Equal(t, VolumeMount{HostPath: "/host/rw", ContainerPath: "/rw", ReadOnly: false}, mounts[2])
+}
+
+func TestParsedVolumes_RelativeHostMadeAbsolute(t *testing.T) {
+	c := &ContainerConfig{Volumes: []string{"./init:/etc/localstack/init/ready.d"}}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 1)
+	assert.True(t, filepath.IsAbs(mounts[0].HostPath), "host path should be absolute, got %q", mounts[0].HostPath)
+	assert.True(t, strings.HasSuffix(mounts[0].HostPath, filepath.FromSlash("/init")), "got %q", mounts[0].HostPath)
+}
+
+func TestParsedVolumes_TildeExpanded(t *testing.T) {
+	home, err := os.UserHomeDir()
+	require.NoError(t, err)
+	c := &ContainerConfig{Volumes: []string{"~/init:/data"}}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 1)
+	assert.Equal(t, filepath.Join(home, "init"), mounts[0].HostPath)
+}
+
+func TestParsedVolumes_WindowsDrivePath(t *testing.T) {
+	c := &ContainerConfig{Volumes: []string{`C:\data:/data:ro`}}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 1)
+	assert.Equal(t, `C:\data`, mounts[0].HostPath)
+	assert.Equal(t, "/data", mounts[0].ContainerPath)
+	assert.True(t, mounts[0].ReadOnly)
+}
+
+func TestParsedVolumes_BarePathIsPersistenceMount(t *testing.T) {
+	// Legacy form: a bare host path (no container part) mounts at the persistence path.
+	c := &ContainerConfig{Volume: []string{"/my/data"}}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 1)
+	assert.Equal(t, VolumeMount{HostPath: "/my/data", ContainerPath: PersistenceContainerPath}, mounts[0])
+}
+
+func TestVolumeDir_ResolvesFromLegacyBarePath(t *testing.T) {
+	c := &ContainerConfig{Volume: []string{"/my/data"}}
+	dir, err := c.VolumeDir()
+	require.NoError(t, err)
+	assert.Equal(t, "/my/data", dir)
+}
+
+func TestParsedVolumes_Errors(t *testing.T) {
+	for _, raw := range []string{
+		"",               // empty
+		":/data",         // empty host
+		"/host:",         // empty container
+		"/host:relative", // container not absolute
+	} {
+		t.Run(raw, func(t *testing.T) {
+			c := &ContainerConfig{Volumes: []string{raw}}
+			_, err := c.ParsedVolumes()
+			assert.Error(t, err)
+		})
+	}
+}
+
+func TestParsedVolumes_VolumeAliasCombined(t *testing.T) {
+	// "volume" and "volumes" are interchangeable aliases; entries are combined.
+	c := &ContainerConfig{
+		Volumes: []string{"/host/a:/a"},
+		Volume:  []string{"/host/b:/b:ro"},
+	}
+	mounts, err := c.ParsedVolumes()
+	require.NoError(t, err)
+	require.Len(t, mounts, 2)
+	assert.Equal(t, VolumeMount{HostPath: "/host/a", ContainerPath: "/a"}, mounts[0])
+	assert.Equal(t, VolumeMount{HostPath: "/host/b", ContainerPath: "/b", ReadOnly: true}, mounts[1])
+}
+
+func TestVolumeDir_ResolvesFromVolumeAlias(t *testing.T) {
+	c := &ContainerConfig{Volume: []string{"/host/state:/var/lib/localstack"}}
+	dir, err := c.VolumeDir()
+	require.NoError(t, err)
+	assert.Equal(t, "/host/state", dir)
+}
+
+func TestValidate_InvalidVolume(t *testing.T) {
+	c := &ContainerConfig{Type: EmulatorAWS, Port: "4566", Volumes: []string{"/host:relative"}}
+	err := c.Validate()
+	assert.ErrorContains(t, err, "invalid volume")
+}

internal/config/default_config.toml

@@ -9,7 +9,14 @@
 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
-# volume = ""    # Host directory for persistent state (default: OS cache dir)
+# volumes = []   # Bind mounts as "host:container[:ro]" ("volume" is an accepted alias).
+#                # Use to mount init hooks (scripts the emulator runs at startup) or to
+#                # set the persistence directory by mounting to /var/lib/localstack
+#                # (default: OS cache dir). A bare host path sets the persistence dir.
+#                # Examples:
+#                #   volumes = ["./init:/etc/localstack/init/ready.d:ro"]
+#                #   volumes = ["/my/data:/var/lib/localstack"]
+#                #   volume  = "/my/data"   # legacy form, same as the line above
 # env = []       # Named environment profiles to apply (see [env.*] sections below)
 
 # Environment profiles let you group environment variables and reference