Your code is already on the Pod. Build the image there.

You have your code on a Pod. You have been experimenting, installing dependencies, and getting your application working. Now you want an image you can share and deploy.

I built Runpod Weld so you can do that build right where you are working. Give it your source files and a Dockerfile, then build and push the image from the Pod. The command is rpweld.

Weld builds and pushes images. It does not run containers, so you need a Pod or a Docker host to run what you build. This post covers both.

Weld is alpha software and an experimental project. Report problems on GitHub rather than to Runpod support. Some Dockerfiles will not work yet, and builds are slower than local Docker. The trade-off is convenience: you can build inside your Pod without moving the work to another machine or setting up a Docker daemon there.

Start with the ready-to-go Runpod template

I’ve made a Runpod template with Weld already installed, so you can skip the manual setup.

1. Open the template and deploy a Pod.
2. Once the Pod is ready, open its terminal.
3. Check that Weld is installed and that the Pod can run builds:

rpweld --version
rpweld doctor

rpweld doctor checks the Pod’s environment, including the Linux capabilities and filesystem permissions that RUN steps need. If it reports a problem, fix that before you start a build.

Optional: install on an existing Pod

Already have a Pod you want to use? This is the manual alternative. Skip it if you launched the template above.

Weld supports Linux amd64 only, and Debian 12 is the validated install target. Check the latest GitHub release for the current version number, set it below, then download, verify, and install the package:

VERSION=0.1.0   # replace with the latest release version
BASE=https://github.com/kodxana/Runpod-Weld/releases/download/v${VERSION}
curl -fLO "${BASE}/rpweld_${VERSION}_amd64.deb"
curl -fLO "${BASE}/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS
apt install ./rpweld_${VERSION}_amd64.deb
rpweld --version
rpweld doctor

‍

Run the install as root, or prefix the apt install command with sudo if your account uses sudo. Using apt install rather than dpkg -i lets apt resolve any missing dependencies. The package bundles Weld’s registry backend (Skopeo) under /usr/lib/rpweld, so you do not need a Rust toolchain or a separate Skopeo installation, and Weld does not replace any Skopeo you already have.

Know where Weld keeps its files

Weld stores build work, output images, and cached base images under ${RPWELD_HOME:-$HOME/.local/share/rpweld}. It keeps finished builds for inspection and does not yet delete old builds automatically, so this directory grows with every build. Check free space with df -h before you start, and run rpweld --help to see the cleanup commands available in your version.

On most Pods, $HOME sits on the container disk, which is wiped when the Pod is reset. If you want the build cache to survive, point Weld at your volume before building:

export RPWELD_HOME=/workspace/rpweld

Keep in mind that volume storage continues to bill while the Pod is stopped.

The images Weld builds live in Weld’s own store, not in Docker’s. Commands such as docker images will not show them.

Build something you can see

Let’s build a tiny web page. Everything you need is below: two files, no repository clone, no model download, and no GPU required.

Create a folder on your Pod:

mkdir weld-demo
cd weld-demo

Save this as index.html inside that folder:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My first Weld image</title>
  <style>
    :root { color-scheme: dark; font-family: system-ui, sans-serif; }
    body { margin: 0; padding: 64px 24px; background: #111319; color: #f4f3ef; }
    main { max-width: 760px; margin: auto; }
    .label { color: #ffb268; letter-spacing: .16em; font-size: 13px; }
    h1 { font-size: clamp(42px, 8vw, 80px); line-height: 1.05; letter-spacing: -.05em; }
    p { color: #c1bec8; font-size: 18px; line-height: 1.7; }
    button { padding: 14px 20px; border: 0; border-radius: 10px; cursor: pointer;
      background: #ffb268; color: #21170f; font: inherit; font-weight: 700; }
    button:focus-visible { outline: 3px solid white; outline-offset: 4px; }
    #status { min-height: 2em; color: #b3e6cc; }
  </style>
</head>
<body>
  <main>
    <p class="label">WELD / MY FIRST IMAGE</p>
    <h1>Built on my Pod.<br>Ready to ship.</h1>
    <p>A little HTML. A Dockerfile. An image built with Runpod Weld.</p>
    <button id="check">Check HTTP response</button>
    <p id="status" role="status">Click to check the server serving this page.</p>
    <p>Weld builds the image. A separate container runtime runs it.</p>
  </main>
  <script>
    document.getElementById('check').addEventListener('click', async () => {
      const status = document.getElementById('status');
      status.textContent = 'Checking...';
      try {
        const response = await fetch('./index.html', {
          method: 'HEAD', cache: 'no-store', signal: AbortSignal.timeout(10000)
        });
        status.textContent = response.ok
          ? 'HTTP ' + response.status + ': your page is being served.'
          : 'The server returned HTTP ' + response.status + '.';
      } catch {
        status.textContent = 'Request failed. Open the page through its HTTP server.';
      }
    });
  </script>
</body>
</html>

Next, save this as Dockerfile in the same folder, with no file extension:

FROM ubuntu:24.04
RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends python3
WORKDIR /site
COPY --chmod=0644 index.html /site/index.html
USER 10001:10001
EXPOSE 8080
CMD ["python3", "-m", "http.server", "8080", "--bind", "0.0.0.0", "--directory", "/site"]

This installs Python and adds your page to the image. Python’s HTTP server is enough for this demo, but it is not intended as a production web server.

Build and publish the image

Create a Docker Hub repository named weld-demo, and create an access token with push access to that repository only. Replace YOUR_USERNAME below with your Docker Hub username, then log in from the Pod. Reading the token from an environment variable keeps it out of your shell history:

printf '%s' "$DOCKERHUB_TOKEN" | rpweld login docker.io --username YOUR_USERNAME --password-stdin

Running rpweld login docker.io without these flags prompts for your credentials instead.

Weld saves registry credentials in ~/.config/rpweld/auth.json. The file is readable only by your user, but the token inside is base64-encoded, not encrypted. Anyone with access to the Pod, or to a template saved from it, can read the token. Log out when you finish, as shown at the end of this section.

Now build and push in one step from the weld-demo folder:

rpweld build -t docker.io/YOUR_USERNAME/weld-demo:demo --push .

Weld pushes the tag only after the build exports successfully. If you prefer to inspect the image before publishing, build first and push as a separate step:

rpweld build -t docker.io/YOUR_USERNAME/weld-demo:demo .
rpweld push docker.io/YOUR_USERNAME/weld-demo:demo

The first build needs internet access to download the base image and the Ubuntu packages. The build does not start the web server; it produces an image.

Want a different headline? Edit index.html and run the build command again. Weld reuses cached stages, so later builds do less work.

When you finish publishing, remove the stored credentials:

rpweld logout docker.io

Run the image on a Pod

You built the image on a Pod, and you can run it on one too. In the Runpod console:

1. Deploy a new CPU Pod. The demo does not need a GPU.
2. Click Edit Template and set the container image to docker.io/YOUR_USERNAME/weld-demo:demo.
3. Add 8080 to the Expose HTTP Ports field.
4. Deploy the Pod and wait for it to start.

Open https://POD_ID-8080.proxy.runpod.net, replacing POD_ID with your Pod’s ID, and click Check HTTP response. You should see your headline and an HTTP 200 message.

If your Docker Hub repository is private, Runpod needs credentials to pull the image. Add them under Settings > Container Registry Authentication in the console, then select them in the template before deploying.

Stop or terminate the Pod when you finish so it does not keep billing. After you publish an updated image, restart the Pod so it pulls the new version.

Alternative: run it with Docker

If you have a machine with Docker and Linux amd64 support, you can run the image there instead. Log in first if your repository is private:

docker pull --platform linux/amd64 docker.io/YOUR_USERNAME/weld-demo:demo
docker run --rm --platform linux/amd64 -p 127.0.0.1:8080:8080 docker.io/YOUR_USERNAME/weld-demo:demo

Open http://localhost:8080 on that machine and click Check HTTP response. Stop the container with Ctrl+C.

Before you try your own Dockerfile

For your own project, run the build from the folder containing your Dockerfile:

rpweld build -t my-app:demo .

Weld follows that Dockerfile. It does not snapshot the running Pod. Weld supports a subset of Dockerfile syntax, so check your Dockerfile against these limits first:

• Linux amd64 only. Weld rejects ARM and multi-architecture targets.
• RUN requires /bin/sh in the image. Distroless base images fail at the first RUN step.
• One syntax directive. The only accepted first line is exactly # syntax=docker/dockerfile:1. Other versions, such as dockerfile:1.4, and custom frontends are rejected. Delete or change that line if your Dockerfile has one.
• Octal modes only for COPY --chmod. --chmod=0644 works; symbolic modes such as u+x do not.
• Static stage references only. Named stages and COPY --from work, but a --from value built from a variable does not.
• No remote ADD. Use RUN curl or COPY instead.
• Restricted RUN --mount. Secret and cache mounts are supported, but one RUN instruction cannot use both.

The Weld repository lists the full set of supported instructions and known gaps. Use only Dockerfiles you trust: RUN steps execute with access to the Pod, and Weld is not a security sandbox.

Report build failures

Weld is still alpha. Dockerfile support is incomplete, Pod configurations vary, and you will find rough edges. If a build fails or something behaves unexpectedly, please submit an issue on the repository.

Include the output of rpweld --version and rpweld doctor --json, the command you ran, the error output, and a small Dockerfile that reproduces the problem if possible. Remove tokens and other secrets before posting. These reports determine what gets fixed next.

Start with the ready-to-go template, get the latest release, or read the source.