This page tells you what the kit isolates, what it does not isolate, and why.
| Asset | Protected | How |
|---|---|---|
| Your host files and processes | Yes | The Docker Sandboxes microVM. The agent sees only the workspace that you mount. |
| Your AWS accounts | Partly | The sandbox gets no AWS credentials. The AWS tools point at LocalStack. The kit does not block AWS endpoints. |
| A LocalStack or other service on your host | Partly | The kit denies loopback names at the sandbox proxy. Under the allow-all policy, another name that resolves to 127.0.0.1 still reaches the host. |
| Your agent credentials | Yes | Docker Sandboxes keeps them on the host. The sandbox gets a placeholder. |
| Your LocalStack auth token | No | The token must be in the sandbox. The agent can read it. |
| The sandbox, from files in the workspace | Partly | The agent runs code from the workspace, and a project lstk config runs at boot. The kit limits the images that a project config can start. |
The agent can read the LocalStack auth token. The kit cannot prevent this.
Docker Sandboxes can keep a credential on the host and add it to outgoing requests as an HTTP header. This does not work for LocalStack, for two reasons:
- LocalStack sends the token in the JSON body of the license request to
api.localstack.cloud, not in a header. - LocalStack also uses the token in the container. It uses the token to check the cached license and to decrypt LocalStack code. A placeholder value fails these steps.
The token gets into the sandbox from sbx run -e LOCALSTACK_AUTH_TOKEN.
sbx stores it with the sandbox. The agent runs with sudo and Docker
access in the sandbox, so it can read the variable, the container
environment, or the process list.
Do these steps to limit the risk:
- Use a token that you can revoke without effect on your other work.
- Revoke the token if you think that it was exposed, for example in a commit or a log.
- Do not give the agent tasks that print or upload environment variables.
- Keep the network policy strict (see below). A strict policy limits where the agent can send data, but it does not remove all paths. Some hosts that the kits allow accept data from any client, for example the analytics and documentation search endpoints.
The agent context tells the agent not to print, log, or commit the token. This is an instruction, not a control.
At boot, the kit starts LocalStack with the project config of lstk:
.lstk/config.toml in the workspace, or the file that LSKIT_LSTK_CONFIG
names. This file comes from the repository, and it runs before the agent
does anything. The image that it starts gets the auth token and the sandbox
Docker socket. Its env profiles also change what LocalStack does, for example
which extensions it installs.
The kit limits this:
- A project config can start only LocalStack images:
localstack/...on Docker Hub, orpublic.ecr.aws/localstack/.... With another image, the start stops, andlskit-statusshowsconfig-rejected. To allow it, create the sandbox with-e LSKIT_ALLOW_ANY_IMAGE=1. - The kit reads the file as TOML, and ignores the case of keys as lstk does, so each way to write an image counts. It refuses a file that is not valid TOML.
- To ignore
.lstk/config.toml, create the sandbox with-e LSKIT_IGNORE_PROJECT_CONFIG=1. The kit then uses its own config.
The image check does not make an untrusted config safe, because the env
profiles still control LocalStack. Treat a project config like a script in
the repository. For a repository that you do not trust, set
LSKIT_IGNORE_PROJECT_CONFIG=1.
The kit sets AWS_ACCESS_KEY_ID=test, AWS_SECRET_ACCESS_KEY=test, and
AWS_ENDPOINT_URL=http://localhost:4566. The AWS CLI, the AWS SDKs,
Terraform, AWS CDK, and AWS SAM send requests to LocalStack.
The kit does not deny AWS endpoints, so that you can decide. With the
allow-all policy, the agent can connect to AWS endpoints, but it has no
valid credentials. If your workspace contains AWS credentials, for example in
a .env file, the agent can read them.
To block AWS endpoints for one sandbox, add deny rules:
$ sbx policy deny network --sandbox ls-claude '**.amazonaws.com'
$ sbx policy deny network --sandbox ls-claude '**.aws.amazon.com'Through the sandbox proxy, loopback is the host. The host can run its own
LocalStack or other local services. localhost.localstack.cloud and its
subdomains resolve to 127.0.0.1, so a client that sends these names to the
proxy reaches the host.
The kit does two things:
- It adds the LocalStack names to
NO_PROXYand to the Java proxy bypass list, for agent shells, lstk, and the MCP server. These clients connect directly to the LocalStack in the sandbox. - It denies
localhost,127.0.0.0/8,::1,host.docker.internal,localhost.localstack.cloud, and**.localhost.localstack.cloudat the proxy. A request for these names through the proxy gets HTTP 403.
This stops accidental access. It does not stop an agent that tries on
purpose: the proxy rules match names, so under the allow-all policy, any
other name that resolves to 127.0.0.1, such as 127.0.0.1.nip.io, still
reaches the host. The balanced and deny-all policies refuse names that no
rule allows, so they close this path.
The sandbox template starts Docker with GODEBUG=tarinsecurepath=0. With
this setting, Go rejects a tar entry whose name is not a local path. The AWS
Lambda base images on public.ecr.aws have a directory entry with an empty
name, so Docker cannot pull them, and LocalStack cannot run Lambda functions.
The kit adds /usr/local/bin/dockerd, a small script that starts
/usr/bin/dockerd with tarinsecurepath=1, which is the Go default. The
setting applies to dockerd and to the processes that it starts:
containerd, which unpacks the layers with the containerd image store, and
the container shims. Other programs in the sandbox keep the template setting.
moby and containerd have their own checks that keep each path of a layer
inside the layer root, as in a standard Docker installation.
The script works only while the template starts dockerd through a PATH
lookup. The smoke test pulls a Lambda image to find a change.
The mixin allows these hosts on port 443. The agent kit adds the hosts that the agent needs.
| Hosts | Used by |
|---|---|
api.localstack.cloud, analytics.localstack.cloud |
License activation and product events |
registry-1.docker.io, auth.docker.io, index.docker.io, production.cloudflare.docker.com, production.cloudfront.docker.com |
LocalStack image pulls |
public.ecr.aws, d2glxqk2uabbnd.cloudfront.net |
Lambda runtime images |
registry.terraform.io, releases.hashicorp.com |
Terraform providers and modules |
registry.npmjs.org, pypi.org, files.pythonhosted.org |
Packages for CDK apps, Lambda code, and tests |
github.com, api.github.com, codeload.github.com, objects.githubusercontent.com, raw.githubusercontent.com |
Source downloads and Terraform modules |
wings.crawlchat.app, us.i.posthog.com |
LocalStack MCP server: documentation search (CrawlChat) and analytics (PostHog) |
Kit allow rules add to your policy. Under the allow-all policy, they have
no effect. Under balanced or deny-all, they are the hosts that the
sandbox can reach. Organization policy can override them. Kit deny rules
(see Services on the host) apply under every policy.
To see which requests the policy blocked, run sbx policy log.
The documentation tool of the LocalStack MCP server sends the search queries
of the agent to CrawlChat (wings.crawlchat.app). The MCP server sends usage
events to PostHog (us.i.posthog.com), unless MCP_ANALYTICS_DISABLED=1 is
set. A query can contain text from your project.
LocalStack, lstk, and the LocalStack MCP server send usage events by default. To turn them off for a sandbox, pass these variables when you create it:
$ sbx run -e LOCALSTACK_AUTH_TOKEN -e LOCALSTACK_DISABLE_EVENTS=1 \
-e MCP_ANALYTICS_DISABLED=1 ...Some LocalStack plans require telemetry. On these plans, LocalStack ignores
DISABLE_EVENTS.