lstk Configuration

lstk uses a TOML configuration file, created automatically on first run.

Config file search order

lstk uses the first config.toml it finds in this order:

1. ./.lstk/config.toml: project-local config in the current directory.
2. $HOME/.config/lstk/config.toml: user config (created here if $HOME/.config/ exists).
3. OS default:
   • macOS: $HOME/Library/Application Support/lstk/config.toml
   • Windows: %AppData%\lstk\config.toml
   • Linux: $XDG_CONFIG_HOME/lstk/config.toml or $HOME/.config/lstk/config.toml

On first run, the config is created at path #2 if $HOME/.config/ already exists; otherwise at the OS default (#3).

To see the active config file path:

lstk config path

To use a specific config file:

lstk --config /path/to/config.toml start

Default configuration

The default config.toml created on first run. The type field reflects whichever emulator you chose at first run (see Emulator types); the example below shows it after choosing Azure, with the comments shortened:

[[containers]]
type = "azure"   # 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
# container_name = ""  # Container name (default: "localstack-<type>", plus "-<tag>" when tag is not "latest")
# image = ""     # Custom image to use instead of the default Docker Hub image
# 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]"
# snapshot = "pod:my-baseline"  # Snapshot REF auto-loaded on start (AWS only)

# CLI behavior
[cli]
# check_for_update_on_startup = false  # Skip the update check on start (default: true)

Config field reference

Field	Type	Default	Description
type	string	"aws"	Emulator type. Set it to "azure" for LocalStack for Azure ("aws" and "snowflake" select the other emulators). Run a single [[containers]] block at a time. See Emulator types.
tag	string	"latest"	Docker image tag. The Azure image is published as "latest" and "dev" only, so there is no version tag to pin to yet (see How do I pin a specific LocalStack version?).
port	string	"4566"	Host port the emulator listens on (1–65535). The in-container port is always 4566.
container_name	string	(derived)	Override the derived container name (localstack-<type>, plus -<tag> when tag is not "latest"). This is also what the emulator reports as MAIN_CONTAINER_NAME. Set it when something outside lstk addresses the emulator by a fixed name, e.g. a sidecar proxy on a CI agent.
image	string	(default)	Full image reference that overrides the default Docker Hub image, e.g. an internal-registry mirror or a locally loaded offline image. If it already carries a tag, tag is ignored; otherwise tag (or latest) is appended.
expose_ports	(int | string)[]	[]	Publish additional container ports on the host, beyond the gateway and service ports lstk publishes by default. Each entry is a bare port number, published on the same host port over both TCP and UDP (e.g. expose_ports = [8080]), or a Docker-style "[host:]container[/proto]" string (e.g. expose_ports = ["5354:5353/udp"]).
volume	string	(OS cache)	Host directory for persistent emulator state. Defaults to <os-cache>/lstk/volume/<derived-name>, where the derived name is localstack-<type>, plus -<tag> when tag is not "latest", even if you set container_name. See also volumes.
volumes	string[]	[]	Docker-style "host:container[:ro]" bind mounts (e.g. init hooks). May also carry the persistence mount (target /var/lib/localstack). See Volume mounts.
env	string[]	[]	List of named environment profiles to inject into the container (see below).
snapshot	string	""	Snapshot REF (e.g. pod:my-baseline or a local path) to auto-load after the emulator starts. AWS emulator only; not available for Azure. See Auto-loading a snapshot on start in the AWS docs.

The [cli] table holds settings for lstk itself rather than for an emulator:

Field	Type	Default	Description
check_for_update_on_startup	boolean	true	Set to false to skip the check for a newer lstk version when the emulator starts. The LSTK_CHECK_FOR_UPDATE_ON_STARTUP environment variable overrides it. lstk update always checks.

Note

lstk also writes check_for_update_on_startup = false for you when you answer Never check again to the update prompt that lstk start shows in an interactive terminal (see Update notification on start).

Emulator types

lstk can run more than one kind of emulator. The type field in your config.toml selects which one:

Type	Docker image	Description
azure	localstack/localstack-azure	LocalStack for Azure.

The other types, aws and snowflake, start the LocalStack for AWS and LocalStack for Snowflake emulators.

On the first interactive run, lstk prompts you to pick an emulator; press z for Azure, and lstk writes your choice to config.toml. Without a config file, a non-interactive run assumes the default aws emulator, so in CI pass --type azure, or commit a config.toml that sets type = "azure".

Lifecycle commands operate on the emulators defined in your config.toml. Run a single [[containers]] block at a time; lstk start refuses to start with more than one. The AWS-specific commands (aws, reset, setup aws, and the resource list of status) need an aws emulator.

Note

The Azure emulator validates its own license inside the container at startup, so lstk skips its pre-flight license check. If your license does not cover Azure, the container exits and lstk shows the reason from the emulator’s output.

Passing environment variables to the container

Define reusable environment profiles under [env.<name>] and reference them in your container config. This example enables the Azure Portal Emulator and accepts the Microsoft SQL Server EULA, which Azure SQL Database needs:

[[containers]]
type = "azure"            # 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
env = ["portal", "mssql"] # Named environment profiles to apply (see [env.*] sections below)

[env.portal]
LS_AZURE_PORTAL = "1"

[env.mssql]
MSSQL_ACCEPT_EULA = "Y"

When lstk start runs, the key-value pairs from each referenced profile are injected as environment variables into the LocalStack container. Keys are uppercased automatically, so ls_log = "debug" reaches the container as LS_LOG=debug.

Note

If you reference an env profile name that doesn’t exist in your config, lstk returns an error: environment "..." referenced in container config not found.

In addition to your custom profiles, lstk always injects several variables into the container. See Container-injected variables for the full list.

Custom container image

By default the Azure emulator image is pulled from Docker Hub (localstack/localstack-azure). Set image on a container block to override it — for example, to pull from an internal-registry mirror or to run a locally loaded image in an air-gapped environment:

[[containers]]
type  = "azure"
image = "registry.internal.example.com/localstack/localstack-azure"
tag   = "latest"

If image already carries a tag (e.g. ...:latest), the separate tag field is ignored; otherwise tag (or latest) is appended. See Offline and enterprise environments for how lstk falls back to a locally present image when a pull fails.

Volume mounts

Beyond the single state directory set by volume, a container block can declare arbitrary Docker-style bind mounts with volumes. Each entry is a "host:container[:ro]" spec — useful, for example, for mounting an initialization script into /etc/localstack/init/{boot,start,ready,shutdown}.d, or for keeping the emulator’s state directory in your project:

[[containers]]
type = "azure"
port = "4566"
volumes = [
  "./init-ready.sh:/etc/localstack/init/ready.d/init-ready.sh",
  "./data:/var/lib/localstack",
]

Note

The Azure emulator doesn’t keep your resources across restarts, even when its state directory is on your host.

• A volumes entry whose container target is /var/lib/localstack sets the persistence directory (the same mount volume configures); this is what lstk volume path and lstk volume clear resolve.
• Relative host sources are resolved against the config file’s directory, and a leading ~/ expands to your home folder. This differs from the legacy volume field, whose value is passed to Docker verbatim.
• Setting the persistence directory through both volume and a volumes entry with a different source is a validation error.

volume and volumes overlap only for the persistence mount: volume can only set the persistence directory, while volumes is a superset that can also express init hooks and other mounts.

Using a project-local config

Place a .lstk/config.toml in your project directory. When you run lstk from that directory, the local config takes precedence over the global one. This lets each project pin its own emulator type, image, and environment profiles.

Caution

lstk writes its own files next to the config.toml it finds: its log, lstk.log, and, when the system keyring is unavailable or LSTK_KEYRING=file is set, your auth token in auth-token. With a project-local config, both end up in .lstk/, so commit only .lstk/config.toml and ignore the rest:

.gitignore

.lstk/*
!.lstk/config.toml

For example, a project that targets the Azure emulator can keep its own config:

.lstk/config.toml

[[containers]]
type = "azure"
port = "4566"

A project that also wants a debug profile might instead use:

.lstk/config.toml

[[containers]]
type = "azure"
port = "4566"
env  = ["dev"]

[env.dev]
DEBUG = "1"