Agent Runtime Extension

In a standard containerized AI Agent, the runtime is “frozen” inside the Docker image. If a user needs a specific version of a tool, a custom CLI, or a proprietary binary, they are stuck. Rebuilding the Agent’s core image for every user requirement is inefficient and creates a massive maintenance overhead.

Instead of a static image, we use a modular runtime. The Agent binary remains stable, while the environment is extended on-the-fly. By using a “Carrier Image” (User-provided) and an initContainer, we decouple the Agent’s logic from its toolset.

How it Works

1. You provide a Docker image containing the tools you need in /opt/snapr/runtime/ path.
2. At startup, the system runs an initContainer that copies your tools into a shared volume.
3. The Agent container mounts this volume and “sources” the new paths into the system shell, making the tools available globally.

User Guide: Extending the Agent

Step 1: Build your Extension Image

Create a Dockerfile that places all required binaries or folders into /opt/snapr/runtime/.

Example: Creating a Go extension

FROM debian:stable-slim

# Install any dependencies
RUN apt-get update && apt-get install -y curl tar && rm -rf /var/lib/apt/lists/*

# Mandatory: Create the staging directory
RUN mkdir -p /opt/snapr/runtime/

# Download Go 1.22
RUN curl -fsSL https://go.dev/dl/go1.22.1.linux-amd64.tar.gz \
    | tar -C /opt/snapr/runtime/ -xz

# Now Go binary is at /opt/snapr/runtime/go/bin/go

Push your image into your desired registry. E.g: my-registry.com/my-custom-runtime:v1

Register via ConfigMap

Snapr looks for a specific ConfigMap named repo-extension-binaries in the snapr namespace. For each repository that requires custom binaries, you must add a key following the org-reponame format. The value is a YAML block defining the image and the internal paths.

apiVersion: v1
kind: ConfigMap
metadata:
  name: repo-extension-binaries
  namespace: snapr
data:
  myorg-myreponame: |
    image: "my-registry.com/my-custom-runtime:v1" # image containing binaries
    bin_paths: ["go/bin"] # specific binaries paths inside '/opt/snapr/runtime/'