> ## Content Index
> Fetch the complete content index at: https://www.dataleadsfuture.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# A Quick Guide to Containerizing Agent Applications with Podman
- URL: https://www.dataleadsfuture.com/a-quick-guide-to-containerizing-agent-applications-with-podman/
- Published: 2025-12-04T09:54:47.000Z
- Updated: 2026-04-22T08:21:03.000Z
- Description: Alternative solutions compatible with Docker SDK
- Author: Peng Qian
- Tags: Agentic AI, Generative AI

## Introduction

For enterprise-level agent applications, the best way to safely run code generated by agents is to use containerization. This isolates the code execution environment from your server’s operating system.

In a previous article, we built a code interpreter sandbox based on a Jupyter container. We proved that once an agent has access to a stateful code runtime, it gains the ability to solve complex problems and perform data analysis:

[Exclusive Reveal: Code Sandbox Tech Behind Manus and Claude Agent SkillsUse Jupyter code executor to help your agent finish tasks in a smarter way![](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/icon/color_192_192-47.png)Data Leads FuturePeng Qian![](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/thumbnail/cover-7.webp)](https://www.dataleadsfuture.com/exclusive-reveal-code-sandbox-tech-behind-manus-and-claude-agent-skills/)

However, Docker Desktop is off-limits in most enterprises due to its commercial license restrictions. 

Yet our multi-agent development work absolutely depends on a containerized environment. So we must find a suitable alternative. Ideally, one fully compatible with Docker, so it works seamlessly with existing agent frameworks that rely on the Docker client.

Podman is exactly what we need. Developed by Red Hat, it’s an open-source container management tool that runs on both Mac and Windows. It can fully replace Docker Desktop in your development setup.

This short post will help you quickly set up Podman so you can start building agent applications with code interpreters right away. If you’d like deeper background knowledge and a more thorough introduction to Podman, I highly recommend the [**Podman for the Absolute Beginners - Hands-On DevOps course on Udemy**](https://www.udemy.com/course/podman-for-the-absolute-beginners-hands-on-devops/?couponCode=KEEPLEARNING)**.**

---

## Quick Start

### Prerequisites

This guide assumes you’re developing on Windows 11\. From what I know, setup on Mac is even simpler.

Podman runs its host inside a Linux system on WSL2\. So before proceeding, make sure you’ve already installed WSL2 on your machine.

If your company requires a VPN to access the internet, you’ll also need to configure WSL2\. To do this, create a `.wslconfig` file in your Windows `%USERPROFILE%` directory (your user folder) with the following content:

```latex
[experimental]
autoMemoryReclaim=gradual  
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true
```

### Install Podman

As mentioned, Podman’s host runs in a WSL2-based Linux environment called `podman-machine-default`. So when installing Podman, you actually need to set up this `podman-machine-default`.

One approach is to install Podman Desktop first, then create the `podman-machine-default` through its interface. But for some reason, this always failed for me—the installer would just hang.

So I went the other way: I installed `podman-machine` standalone first, then installed Podman Desktop. Go to Podman’s [GitHub Releases page](https://github.com/containers/podman/releases), download the latest `.msi` installer, and run it.

![Find and download the .msi installer under the latest release.](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/2025/12/image.png)

Find and download the .msi installer under the latest release. Image by Author

After installation, create your `podman-machine-default` host:

```shell
podman machine init --rootful=true
```

Important note: if your agent framework uses the Docker SDK to launch containers, you **must** set `--rootful=true`. I’ll explain why later.

Next, install Podman Desktop from [here](https://podman-desktop.io/). Just click “Next” all the way through.

Once done, open Podman Desktop from your taskbar, go to the **Settings** tab, and check **Resources**. You should see the `podman-machine` you just created. That means Podman Desktop is ready.

![If you see this screen, it means your Podman Desktop is already installed.](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/2025/12/image-1.png)

If you see this screen, it means your Podman Desktop is already installed. Image by Author

But since your agents will use the Docker SDK to manage containers, you need to enable Docker compatibility in Podman Desktop, as shown below:

![We use the Docker SDK to manage containers in our agent framework, so make sure Docker Compatibility is turned on.](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/2025/12/image-2.png)

We use the Docker SDK to manage containers in our agent framework, so make sure Docker Compatibility is turned on. Image by Author

This setting also enables Podman Compose, which lets you route `docker compose` commands to `podman compose`.

### Set up proxy configuration

If your system uses a system-wide proxy, Podman Desktop will automatically pick it up. But here’s the catch: Podman Desktop applies these settings inside the `podman-machine` Linux system. Unlike Windows, where bypass domains are separated by semicolons, Linux uses commas. You’ll need to manually adjust this, or your `podman-machine` might lose external network access.

![You should use the Linux path separator here.](https://storage.ghost.io/c/33/67/33678c00-2c15-4961-93e9-497b427e2006/content/images/2025/12/image-3.png)

You should use the Linux path separator here. Image by Author

### Create a soft link for the storage path

By default, Podman stores data in `%USERPROFILE%\.local\share\containers\podman`.

I really dislike keeping data files on the C drive. I prefer moving them to D drive—for example, `D:\Documents\AppData\podman`.

Here’s how: copy everything from the C-drive `podman` folder to your new D-drive location, delete the original C-drive folder, then create a junction link (remember to replace `%USERPROFILE%` with your actual path):

```shell
mklink /j C:\Users\qianpeng\.local\share\containers\podman D:\Documents\AppData\podman
```

Now everything works normally, but your data lives safely on D drive—no risk of losing it during a system reinstall.

### Test your Podman installation

If you followed my [earlier article](https://www.dataleadsfuture.com/exclusive-reveal-code-sandbox-tech-behind-manus-and-claude-agent-skills/) and created a `Dockerfile` for a `jupyter-server`, you can now test whether Podman builds images correctly. Navigate to your `Dockerfile` directory and run:

```shell
podman build --network=host -t jupyter-server .
```

Remember, the `podman-machine` host is network-isolated from your Windows system. The `--network=host` flag lets the build process access your Windows network, making it easier to pull base images and install Python packages from PyPI.

Note: this flag only affects image building—it has no impact when running containers.

### Make Docker CLI commands work

If you’re used to typing `docker` commands, here’s a neat trick: create a `docker.bat` file in `%USERPROFILE%/.local/bin` (Make sure this path is in your system `PATH`).

Put this inside `docker.bat`:

```shell
@echo off
setlocal EnableDelayedExpansion
if "%~1"=="build" (
	shift
	rem Default to --network=host
	podman build --network=host %2 %3 %4 %5 %6 %7 %8 %9
) else (
	podman %*
)
endlocal
```

Now you can keep using `docker` commands as usual. Since Podman’s CLI is mostly compatible with Docker’s, everything feels the same—except when you run `docker build`, it automatically adds `--network=host` to the underlying `podman build` command.

### Call Docker SDK from inside a containerized app

If your agent app runs inside a container and needs to use the Docker SDK to spin up Python code interpreter containers (a common pattern across agent frameworks), you’ll need to let the SDK talk to Podman.

Do this by mounting the `podman.sock` socket into your app container so the Docker SDK can reach it:

```shell
docker run -v /run/podman/podman.sock:/var/run/docker.sock --rm app-test
```

Again, your `podman-machine-default` **must** be initialized with `--rootful=true`.

### Fix Docker SDK timeout issues

When your agent generates code and sends it via Docker SDK to a code interpreter container, there’s often a delay between code generations while the LLM produces tokens. On the second SDK call, you might hit a timeout like this:

```latex
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
```

This happens because `podman-machine` sets a very short `service_timeout` for its engine by default.

Fix it by SSHing into your `podman-machine`:

```shell
podman machine ssh
```

Now you’re in the Linux VM. Edit `/etc/containers/containers.conf`:

```shell
sudo vi /etc/containers/containers.conf
```

Set `service_timeout` to 0 (meaning “never time out”) under the `[engine]` section:

```shell
[engine]
cgroup_manager = "cgroupfs"
service_timeout = 0
```

Since this is a dev environment, security isn’t a concern here.

### Adjust Podman container stop timeout

During development, you often start and stop your agent program from the command line. But you might notice it takes forever to exit after the program finishes.

That’s because Podman waits by default (10 seconds!) for containers to gracefully shut down after receiving a stop signal.

Shorten this by editing the same config file:

```shell
[engine]
stop_timeout = 2
```

Now containers stop in 2 seconds—much snappier!

### Allow Containers to Use the --restart Flag

Podman lets you use the `--restart` flag when starting a container, just like Docker, so your containers can automatically start up again after your computer reboots.

The only thing you need to do first is set up `podman-restart.service` inside your podman-machine. Here's how:

First, jump into podman-machine-default and run these shell commands:

```shell
# Check the status of podman-restart.service
systemctl status podman-restart.service
# Enable the service (so it starts on boot)
sudo systemctl enable podman-restart.service
# Start the service right now
sudo systemctl start podman-restart.service
```

Then create your container with the `--restart` flag:

```shell
podman run -d -p 5000:5000 --name mlflow-server --restart=always mlflow-server
```

Or if the container already exists, just update its restart policy:

```shell
podman update --restart=always mlflow-server
```

Finally, to make sure everything is set up correctly, run this in your Windows terminal:

```shell
podman inspect mlflow-server --format='{{.HostConfig.RestartPolicy.Name}}'
```

And that's it, you're good to go!

---

## Conclusion

Ever since Gemini 3.0 accidentally deleted 800GB of user data, running agent-generated code inside containers has become essential. And yes—stateful code interpreters truly boost an agent’s ability to tackle complex problems.

Most agent frameworks rely on the Docker SDK to manage containers. But Docker Desktop’s licensing blocks its use in enterprise dev environments.

This guide shows you how to use Podman Desktop as a drop-in replacement. Following these steps, you can quickly build a Docker-compatible container dev environment. I’ve used this exact setup for over six months with zero issues.

This article covers only the minimal setup needed for agent development. If you want to dive deeper into Podman’s internals and advanced usage, check out the official tutorials.

Our journey toward **Deep Data Analyst Agents** continues—stay tuned for the next episode!

## Follow Data Leads Future

One practical story every month, sharing my hard-learned experiences in the enterprise AI space.

Subscribe 

Email sent! Check your inbox to complete your signup. 

You can unsubscribe anytime.