RamaLama: container-native model runner using the Ollama registry
Parent: Ollama · Published reference · snapshot 2026-10-15 · skill ollama-expert/references/ramalama-and-ollama-registry.md
Also known as: RamaLama
↓ Facts as markdownall context files
Source-anchored research for RamaLama: container-native model runner using the Ollama registry. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- Shortnames are the supported way to avoid typing a prefix: a short name resolves through shortnames.conf to a backing registry. A Red Hat blog (2025-12-17) shows gpt-oss mapping to Hugging Face, and v0.22.0 added Hugging Face targets for names commonly used in the Ollama library (llama3*, phi3/phi4, gemma2, qwen2/qwen2.5, mixtral, codellama, deepseek-coder, mistral-nemo, smollm2), so `ramalama run llama3.1:8b` no longer needs a full repository URL. Use `ramalama list` (which shows a shortname column since v0.23.0) to see how a stored model was resolved. (medium confidence) (verified as of 2026-10-14) [source]
How it works
- Current behaviour, verified in the code at v0.25.0 (2026-09-25, the latest release on 2026-10-14): RamaLama has no implicit default transport. Resolution order for a model name is: an explicit prefix (ollama://, huggingface://, hf://, hf.co/, modelscope://, ms://, oci://, docker://, rlcr://, http(s)://, file:); then a name containing a slash goes to Hugging Face when no transport is configured; then a transport set by RAMALAMA_TRANSPORT, --transport or the transport key in ramalama.conf; otherwise a KeyError reads "'<model>' is not a known shortname and no transport was specified. Use a shortname from shortnames.conf, or specify a transport explicitly". The Ollama transport still works when you ask for it: ollama://, --transport ollama, or RAMALAMA_TRANSPORT=ollama. The dataclass default transport = "ollama" in config.py does not act as an implicit default: New() passes a configured transport to TransportFactory only when config.is_set("transport") is true, meaning the value was set explicitly in a config file, the environment or the command line, and TransportFactory's own transport parameter defaults to None. (high confidence) (verified as of 2026-10-14) [source]
- RamaLama stores pulled models under $HOME/.local/share/ramalama when rootless (the README says the model store defaults to ~/.local/share/ramalama) and /var/lib/ramalama when rootful; override with --store, RAMALAMA_STORE or ramalama.conf. It is its own store, not ~/.ollama. (medium confidence) [source]
- ramalama serve listens on 127.0.0.1 by default (--host) and uses port 8080 when it is free. When 8080 is taken the docs disagree on the fallback: the serve man page says the first free port between 8080 and 8180, the README says a free port in 8081-8090. The man page defers to each runtime for the HTTP API (vLLM links to its OpenAI-compatible server), so the OpenAI-compatible endpoint belongs to the runtime server, not to RamaLama. (medium confidence) (verified as of 2026-10-14) [source]
- Choose RamaLama when a model must run inside a rootless container with no network (ramalama run uses --network=none, a read-only model mount, dropped capabilities and --rm), when you want Podman Quadlet, Kubernetes YAML or Compose output from `ramalama serve --generate`, or when you want to publish models as OCI artifacts with `ramalama push`. (medium confidence) [source]
- Choose Ollama when you need Modelfile control (TEMPLATE, SYSTEM, PARAMETER) or the `ollama launch` integrations: both are documented Ollama features (Modelfile reference, CLI reference), and the RamaLama sources read for this page describe no equivalent. RamaLama pulls Ollama models into its own store, not ~/.ollama. (medium confidence) (verified as of 2026-10-14) [source]
Problems, failure modes and limitations
- RamaLama selects a model transport by URI prefix: ollama://, huggingface:// (hf://, hf.co/), modelscope://, oci:// (docker://), rlcr://, https://, http://, file://. The openai:// hosted-API transport is deprecated. (high confidence) (verified as of 2026-10-14) [source]
- RamaLama prefers Podman when both Podman and Docker are installed; RAMALAMA_CONTAINER_ENGINE=docker overrides this. With no engine it tries to run on the host. The `rag` command needs Podman because Docker cannot mount images. --pull defaults to `missing`. (high confidence) [source]
- ramalama run uses --network=none; hosted-API transports such as openai:// bypass the container sandbox and are deprecated; use `ramalama chat --url <endpoint> --api-key <key> --model <model>` instead. --nocontainer disables containers, GPU acceleration and isolation. Images are tagged by RamaLama minor version (for example quay.io/ramalama/cuda:1.2 for 1.2.x); override with --image or RAMALAMA_IMAGE. (medium confidence) (verified as of 2026-10-14) [source]
Comparisons and alternatives
- Default transport history (containers/ramalama): up to v0.20.0 (before 2026-05-14) a name with no prefix used the Ollama transport, because TransportFactory took transport="ollama" by default. v0.21.0 (2026-05-14, PR #2743 "Begin deprecation of ollama model support") made a name containing a slash default to Hugging Face, added a deprecation warning when pulling an Ollama model, and removed Ollama references from shortnames.conf. v0.22.0 (2026-06-05, PR #2748) added Hugging Face GGUF shortnames with Ollama-style names such as llama3.1:8b. v0.23.0 (2026-06-24, PR #2803) relaxed the deprecation "now that ollama is pivoting back to llama.cpp", removed the warning, and made an unknown shortname raise an error instead of silently using the Ollama transport. (high confidence) (verified as of 2026-10-14) [source]
- Why the code changed: the PR #2803 description says a number of Ollama models remain incompatible with llama.cpp, so an unknown shortname should fail with a clear message rather than quietly fetch an Ollama model that may not run. To stay safe in scripts and docs, put the prefix on every model (ollama://tinyllama or huggingface://org/model) or set RAMALAMA_TRANSPORT explicitly. (medium confidence) (verified as of 2026-10-14) [source]
- Pin the transport instead of relying on a default: use an explicit prefix, the --transport option, or RAMALAMA_TRANSPORT/ramalama.conf. The ramalama(1) man page lists huggingface://, hf://, hf.co/, modelscope://, ms://, ollama://, rlcr://, oci://, https://, http:// and file://. (medium confidence) (verified as of 2026-10-14) [source]
Facts and statements
- RamaLama inspects the host for GPU support (falling back to CPU) and uses a container engine to pull an image matching the detected accelerator, so the user does not configure the host. Image families include ROCm, CUDA, Intel GPU, Asahi, CANN, MUSA, plus a default Vulkan/CPU image; images are tied to the RamaLama minor version. (high confidence) [source]
- The ramalama(1) man page on main agrees with the code: models in <org>/<model> form without a prefix are pulled from Hugging Face, the default transport can be overridden in ramalama.conf or with RAMALAMA_TRANSPORT (for example RAMALAMA_TRANSPORT=huggingface), and shortnames resolve through shortnames.conf. (medium confidence) (verified as of 2026-10-14) [source]
- The README on main (last commit 2026-10-02) is stale on this point: it still says org-less names such as granite-code "currently" default to the Ollama transport and that Ollama support "will be removed in a future release", and its pull section says a pull is "by default" from the Ollama registry. The v0.23.0 change (PR #2803) and the v0.25.0 code contradict both statements. Likewise, a February 2026 guide that calls Ollama the default matched releases of that period (the guide shows ramalama 0.17.1; v0.17.0 shipped 2026-02-04) but not v0.23.0 or later. (medium confidence) (verified as of 2026-10-14) [source]
- RamaLama runs models in rootless, unprivileged containers by default: read-only model mount, --network=none for `ramalama run`, --rm cleanup, dropped Linux capabilities, no-new-privileges, SELinux separation on. --privileged and --keep-groups weaken this isolation. (high confidence) [source]
- On macOS, GPU sharing for containers typically needs krunkit and libkrun (Red Hat Developer); a working setup in one guide uses a Podman machine with the LibKrun provider. Multiple served models need distinct host ports (8080, 8086 in the example), and port 8080 may collide with other local services. (medium confidence) [source]
- ramalama serve defaults to the llama.cpp runtime; --runtime=vllm selects vLLM, and --runtime=mlx selects MLX (requires --nocontainer, macOS on Apple Silicon and the mlx-lm tool on the host). --runtime-args passes extra flags; --ctx-size/-c sets context. (medium confidence) [source]
- ramalama serve --generate=quadlet|kube|quadlet/kube|compose emits a Podman systemd Quadlet, Kubernetes YAML, Kubernetes YAML plus a Quadlet that runs it, or Compose YAML; append :<dir> to choose the output directory. A Red Hat blog describes the same capability as generating Quadlet files for edge deployment and Kubernetes manifests for clusters. (medium confidence) (verified as of 2026-10-14) [source]
- ramalama push is OCI-only: `ramalama push ollama://tinyllama:latest oci://quay.io/<org>/tiny:latest` converts a stored Ollama model to an OCI image and pushes it. --type raw|car sets the layout (car puts the model under /models in a base image; raw holds the model plus a model.file link at /). --authfile and --tls-verify (default true) apply. `ramalama convert` builds the OCI model without pushing. (medium confidence) (verified as of 2026-10-14) [source]
- On a Mac, RamaLama's MLX runtime (--runtime=mlx) needs --nocontainer, Apple Silicon and mlx-lm installed on the host, which drops the container isolation that is RamaLama's main advantage; the README lists llama.cpp or MLX as the choices for an Apple Silicon GPU. (medium confidence) (verified as of 2026-10-14) [source]
Children
- OCI model artifacts and ramalama push (frontier)
- Ollama's move off llama.cpp and model compatibility (frontier)
- RamaLama Quadlet and Kubernetes generation (frontier)
- RamaLama container security defaults (frontier)
- RamaLama transports and URI prefixes (frontier)
- RamaLama vLLM runtime and image selection (frontier)
Frontier under this node: OCI model artifacts and ramalama push, Ollama's move off llama.cpp and model compatibility, RamaLama Quadlet and Kubernetes generation, RamaLama container security defaults, RamaLama transports and URI prefixes, RamaLama vLLM runtime and image selection