Kapso deployment strategies: local, Docker, Modal and more

deploy() takes a strategy that decides where the solution runs. Five ship, plus AUTO, which picks one for you.

Which strategy should I use?

Strategy	Suits	Startup	Isolation	GPU	Interface
`LOCAL`	Development and debugging	Fast	None	Local only	function
`DOCKER`	Anything with system dependencies	Medium	Full	Via nvidia-docker	http
`MODAL`	GPU work you do not want to host	Medium	Full	Yes	function
`BENTOML`	Self-hosted production serving	Medium	Full	Yes	http
`LANGGRAPH`	Stateful agent workflows	Fast	None	Via backend	langgraph

In Python the values are DeployStrategy.LOCAL and so on; on the CLI they are lowercase, as --strategy docker.

Local

Runs the solution as a plain Python process in the current environment. Nothing to install, easiest to debug, no isolation.

deployed = kapso.deploy(solution, strategy=DeployStrategy.LOCAL)
result = deployed.run({"data_path": "./data.csv"})

The adapter ensures a main.py exposing predict() and the runner imports it. Its run_interface is {type: function, module: main, callable: predict}.

Docker

Runs the solution in a container, so system dependencies and Python versions stay contained. Needs Docker installed and running.

deployed = kapso.deploy(solution, strategy=DeployStrategy.DOCKER)

Served over HTTP at http://localhost:<port>/predict from a container named kapso-<solution>-<hash>; the name and the host port are derived from the solution’s path, so two solutions deployed on one machine keep their own container, image and port, and a re-deploy replaces only its own. The container runs as an unprivileged user, restarts with the daemon, and is recreated by start() with the same environment variables and, when the selector granted one, the GPUs.

Dockerfile the adapter generates

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN useradd --create-home --uid 1000 app && chown -R app:app /app
USER app
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health', timeout=2).status == 200 else 1)"
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

The runner needs the Docker SDK and requests: pip install "leeroo-kapso[deploy]". Runs on Modal’s serverless platform, which is the quickest route to a GPU you do not have to operate. Needs pip install modal && modal token new.

deployed = kapso.deploy(solution, strategy=DeployStrategy.MODAL)

The app is named kapso-<solution>-<hash> and exposes a predict function plus a web endpoint. An explicit DeployStrategy.MODAL deploy runs on CPU; under AUTO the selector names a GPU (T4, A10G, …) when the code needs one, and the adapter sets gpu= from it. stop() removes the app; start() runs modal deploy again from the adapted workspace. Install with pip install "leeroo-kapso[modal]".

import modal

app = modal.App("solution-name")

image = (
    modal.Image.debian_slim(python_version="3.11")
    .pip_install("fastapi>=0.100.0")
    .add_local_file("main.py", "/root/main.py")
)

@app.function(
    image=image,
    # gpu="T4",  # Uncomment if GPU needed: "T4", "A10G", "A100"
    timeout=300,
)
def predict(inputs):
    ...

BentoML

Packages the solution as a BentoML service and deploys it to BentoCloud (a BENTO_CLOUD_API_KEY is required; serving without BentoCloud is not wired yet). Needs pip install "leeroo-kapso[bentoml]".

deployed = kapso.deploy(solution, strategy=DeployStrategy.BENTOML)

Default resources are 2 CPUs and 4Gi of memory, served at /predict against the bentocloud provider.

BentoML service the adapter generates

import bentoml

@bentoml.service
class KapsoService:
    @bentoml.api
    def predict(self, inputs: dict) -> dict:
        return self.model.predict(inputs)

LangGraph

Deploys the solution as a LangGraph agent workflow, with state, tools, streaming and checkpoints, on LangGraph Platform (a LANGSMITH_API_KEY is required). Needs pip install "leeroo-kapso[langgraph]".

deployed = kapso.deploy(solution, strategy=DeployStrategy.LANGGRAPH)
result = deployed.run({"query": "What is 2+2?"})

The adapter writes agent.py, main.py and langgraph.json; the runner calls the deployed graph on LangGraph Platform via langgraph_sdk, against assistant id agent.

How does AUTO choose?

AUTO is the default. A selector agent reads the solution and picks a target from the code itself rather than from a rule table:

deployed = kapso.deploy(solution, strategy=DeployStrategy.AUTO)

It weighs how complex the code is, what it needs at runtime — GPU, memory, system packages — and whether isolation is required. Each strategy ships a selector_instruction.txt describing when it is the right answer, so the choice is made from those descriptions. Name a strategy explicitly when you already know the answer; AUTO costs a model call.

How do I pass environment variables?

deployed = kapso.deploy(
    solution,
    strategy=DeployStrategy.DOCKER,
    env_vars={"API_KEY": "...", "MODEL_PATH": "/models/v1"},
)

On the CLI, repeat --env:

kapso deploy --solution-path ./solution --strategy docker \
    --env API_KEY=xxx --env MODEL_PATH=/models/v1

The variables are written to .env in the adapted workspace (owner-only permissions; an existing .env keeps its other lines), and the adapter session sees their names, never their values. At runtime Kapso sets them itself where it owns the process: in the local runner’s environment before main is imported, and on the Docker container both at the first docker run --env-file .env and whenever start() recreates it. For Modal, BentoCloud and LangGraph the adapter attaches the file to the deployment (modal.Secret.from_dotenv(), envs: in bentofile.yaml, "env": ".env" in langgraph.json).

What is checked before the software is handed back?

After the adapter session, the adaptation is validated: every Python file must compile, the files the strategy’s config.yaml names under required_files must exist, and — for LOCAL, the one target that runs in this interpreter — main must import. A failed check is sent back to the agent with the finding, up to two more times; a deployment that still fails validation raises instead of handing back software that cannot run.

Deployment architecture

How the selector, adapter and runner fit together

Adding a strategy

Write your own target

Related pages: Deployment architecture · Adding a strategy · Deployment Kapso is an open-source framework by Leeroo that builds software toward measurable goals through experiment campaigns. Source code: github.com/Leeroo-AI/kapso · Install: pip install leeroo-kapso · Every page as plain text: llms.txt.

Getting started

Evolve system

Knowledge graph

Trajectory learning

Research

Deployment

Benchmarks

Kapso deployment strategies: local, Docker, Modal and more

Which strategy should I use?

Local

Docker

BentoML

LangGraph

How does AUTO choose?

How do I pass environment variables?

What is checked before the software is handed back?

Deployment architecture

Adding a strategy

​Which strategy should I use?

​Local

​Docker

​Modal

​BentoML

​LangGraph

​How does AUTO choose?

​How do I pass environment variables?

​What is checked before the software is handed back?

​Related

Deployment architecture

Adding a strategy

Which strategy should I use?

Local

Docker

Modal

BentoML

LangGraph

How does AUTO choose?

How do I pass environment variables?

What is checked before the software is handed back?

Related