DEV Community

Cover image for Running Kiro Crew in Docker on Windows
AWS profile image Matheus Guimaraes
Matheus Guimaraes for AWS

Posted on

Running Kiro Crew in Docker on Windows

#ai #docker #security #devops

I've been playing with Kiro Crew recently, and when I went to get it running on my Windows machine I had a decision to make.

Kiro Crew doesn't currently have a Windows desktop app. You can still run it natively on Windows, but the documented route involves installing and running the Gateway from source.

But then, while looking through the Kiro Crew GitHub repository, I noticed another option that immediately caught my attention: there's an official Docker image!

Docker is already a familiar part of the development workflow for many of us, and a container felt like a nice, clean way to get Kiro Crew running without installing it from source.

So that's the route I took.

It worked, but along the way I ran into an interesting security detail that made the setup slightly less straightforward than simply running a container.

And, as it turns out, that's actually a good thing.

What we're going to do

By the end of this post, we'll have Kiro Crew running in Docker on Windows, with its agent sandbox enabled and without giving the container more privileges than it actually needs.

I'm using Docker Desktop with WSL 2, so you'll want to have those installed before following along.

You can check your WSL installation with:

wsl --version
Enter fullscreen mode Exit fullscreen mode

With that out of the way, let's get Kiro Crew running.

Starting with the official container image

The Kiro Crew team publishes a public container image, so we don't need to build anything ourselves or even authenticate with a container registry. Nice and easy.

Before doing anything else, I created a directory to keep the files for this setup together:

mkdir kiro-crew
cd kiro-crew
Enter fullscreen mode Exit fullscreen mode

Now, at first glance, running Kiro Crew looks like it should be as simple as starting the official image.

And technically, the Gateway itself will run.

But there's another security boundary inside that container that we need to understand before we can start it properly.

Wait... a sandbox inside a container?

This was the interesting part for me.

We're already putting Kiro Crew inside a Docker container, which gives us an isolation boundary between Kiro Crew and our Windows host.

But Kiro Crew adds another boundary of its own.

Agent commands aren't simply executed with access to everything available to the main Kiro Crew process. On Linux, Kiro Crew creates an internal user-namespace sandbox for those commands.

Conceptually, our setup looks something like this:

Windows
└── Docker container
    └── Kiro Crew
        └── Agent sandbox
Enter fullscreen mode Exit fullscreen mode

Why sandbox an agent that's already inside a container?

Because the two boundaries are protecting different things.

The container isolates Kiro Crew from our host. The inner sandbox isolates agent commands from sensitive state available to Kiro Crew itself.

For example, Kiro Crew's sandbox hides credential directories such as ~/.aws and ~/.ssh from agent subprocesses by bind-mounting empty directories over them. So if an agent-executed command tries to access one of those directories, it simply sees an empty directory rather than our AWS credentials or SSH keys.

That means the Gateway can have the credentials it needs to do its job without automatically making those credentials readable by commands executed by an agent.

That's a pretty important distinction when we're giving an AI agent the ability to execute commands.

Where Docker gets in the way

There's one complication.

To create that inner sandbox, Kiro Crew needs Linux system calls including:

unshare(CLONE_NEWUSER)
unshare(CLONE_NEWNS)
Enter fullscreen mode Exit fullscreen mode

Docker's default seccomp security policy blocks those operations.

So if the Kiro Crew container can't create its inner sandbox, it doesn't quietly shrug its shoulders and run agent commands without one.

It fails closed, meaning that when the security mechanism can't be established, access is denied rather than silently falling back to a less secure mode.

The Gateway and dashboard can still run, but agent command execution remains disabled.

I actually really like this design! What initially looks like an extra hurdle in getting the container running is Kiro Crew refusing to silently weaken its security model.

So how do we fix it?

The tempting solution and the better solution

There are a few ways we could approach this.

One option is to simply tell Kiro Crew that we accept running agent commands without the inner sandbox. Kiro Crew provides an environment variable for exactly that:

KIROCREW_ALLOW_UNSANDBOXED=1
Enter fullscreen mode Exit fullscreen mode

We could pass that into our container and Kiro Crew would allow agent execution, leaving Docker itself as our only isolation boundary.

We could also reach for the rather large hammer:

--privileged
Enter fullscreen mode Exit fullscreen mode

That would make the sandbox work, but it does so by granting the container extremely broad privileges and removing many of Docker's normal isolation restrictions.

That's a much bigger security concession than we actually need.

What we really want is much narrower:

Allow the operations Kiro Crew needs to create its sandbox while keeping the rest of Docker's security restrictions in place.

And this is another nice detail about the Kiro Crew implementation: the team already provides a seccomp profile specifically for this!

So we don't have to create one ourselves.

Downloading the Kiro Crew seccomp profile

From the kiro-crew directory we created earlier, download the official Kiro Crew seccomp profile:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o kirocrew-seccomp.json
Enter fullscreen mode Exit fullscreen mode

You should now have:

kiro-crew/
└── kirocrew-seccomp.json
Enter fullscreen mode Exit fullscreen mode

Having trouble downloading it from WSL?

I happened to be dealing with a DNS issue in my WSL environment when I did this, so curl couldn't resolve GitHub. If you happen to run into the same thing, there's nothing special about downloading the file through curl: you can download kirocrew-seccomp.json directly from the Kiro Crew GitHub repository in your browser and place it in this directory manually, which is what I did.

Now we can start the container using that profile.

Running Kiro Crew

Run:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  --security-opt seccomp=kirocrew-seccomp.json \
  ghcr.io/kirodotdev/kirocrew:stable
Enter fullscreen mode Exit fullscreen mode

There are a couple of things worth noticing here.

We're only publishing port 5476 on the host's loopback interface, so the dashboard isn't being exposed to the rest of our network.

We're also creating a named Docker volume:

kirocrew-home
Enter fullscreen mode Exit fullscreen mode

Kiro Crew keeps its persistent state under /home/kirocrew, including its configuration and Kiro CLI credentials. That means our state can survive replacing or upgrading the container.

And, most importantly for what we've just discussed, we're passing the Kiro Crew seccomp profile with:

--security-opt seccomp=kirocrew-seccomp.json
Enter fullscreen mode Exit fullscreen mode

The container can now create the inner namespace sandbox while Docker's other default security restrictions remain in place.

Let's open it

At this point I did what I imagine most developers would do.

I opened:

http://localhost:5476
Enter fullscreen mode Exit fullscreen mode

And instead of the Kiro Crew dashboard, I was greeted by a message telling me I was missing a token.

Kiro Crew dashboard showing that an access token is required

Another security measure!

Simply being able to reach port 5476 isn't enough to get access to the dashboard. Kiro Crew also requires a bearer token, so someone who can reach the Gateway still needs to authenticate before they can use it.

So, there's one more part of the setup we need to do.

Actually, two.

Authenticating Kiro CLI

Kiro Crew's agent runtime uses kiro-cli, so first we need to authenticate the CLI running inside our container.

We can do that without opening an interactive shell ourselves:

docker exec -it kirocrew kiro-cli login
Enter fullscreen mode Exit fullscreen mode

Follow the authentication flow and log in with the identity you use for Kiro.

Once authentication succeeds, those credentials are stored in the kirocrew-home volume we created earlier, so they survive container upgrades.

But that authenticates the agent runtime.

We still need access to the dashboard.

Getting our dashboard token

Every request to the Kiro Crew dashboard requires a token.

We can mint a temporary login link from the running container:

docker exec kirocrew kirocrew token --ttl 2h
Enter fullscreen mode Exit fullscreen mode

Kiro Crew will print a URL containing the token.

It will look roughly like:

http://localhost:5476/?token=...
Enter fullscreen mode Exit fullscreen mode

Open that URL in your browser and...

Kiro Crew running successfully in Docker on Windows

We're in!

And with that, we have Kiro Crew running nicely inside Docker on Windows, without having to build it from source and without unnecessarily weakening either of its isolation boundaries.

Now I just need someone to explain why the Solarized theme is green instead of yellow. 😄

References

Top comments (0)