[Exploration] docs: add Flox in Containers section

docs/concepts/flox-vs-containers.md

@@ -424,6 +424,10 @@ you need to build a container so that it can be deployed.
     You can also produce build artifacts from a Flox environment.
     See the [builds documentation][builds] for more information.
 
+    For an alternative that doesn't require image rebuilds, see
+    [Thin Containers][thin-containers], which resolve environments at
+    startup from a shared Nix store.
+
 === "Containers"
 
     Typically your `Dockerfile` will contain multiple stages,
@@ -447,3 +451,4 @@ you need to build a container so that it can be deployed.
 [manifest]: ../concepts/environments.md#manifesttoml
 [builds]: ../concepts/builds.md
 [ci-cd]: ../tutorials/ci-cd.md
+[thin-containers]: ../containers/thin-containers/intro.md

docs/containers/containerize/getting-started.md

@@ -0,0 +1,118 @@
+---
+title: "Getting started with Containerize"
+description: "Build a container image from a Flox environment."
+---
+
+# Getting started with Containerize
+
+This guide walks you through building a traditional OCI container image from a Flox environment using [`flox containerize`][containerize-man].
+
+!!! tip
+    If you don't need a self-contained image, consider using [thin containers](../thin-containers/intro.md) instead.
+    Thin containers resolve environments at startup and don't require image rebuilds when your environment changes.
+
+## Prerequisites
+
+- The [Flox CLI][flox-install]
+- [Docker][docker-install] or [Podman][podman-install] (required on macOS; optional on Linux)
+
+## 1. Create an environment
+
+Create a new environment and install some packages:
+
+```{ .bash .copy }
+mkdir myproject && cd myproject
+flox init
+flox install hello curl
+```
+
+## 2. Build the image
+
+Load the image directly into your container runtime:
+
+```{ .bash .copy }
+flox containerize --runtime docker
+```
+
+Alternatively, write the image to a file:
+
+```{ .bash .copy }
+flox containerize -f myproject.tar
+```
+
+You can then load the file into Docker manually:
+
+```{ .bash .copy }
+docker load -i myproject.tar
+```
+
+!!! note "macOS"
+    On macOS, `flox containerize` uses a proxy container (Docker or Podman) to build the Linux image.
+    You may be prompted for file-sharing permissions on the first run.
+
+## 3. Run the container interactively
+
+```{ .bash .copy }
+docker run --rm -it <image-id>
+```
+
+You'll be dropped into a shell with the environment activated --- all your packages and environment variables are available:
+
+```{ .console .no-copy }
+[floxenv] $ hello
+Hello, world!
+[floxenv] $ curl --version
+curl 8.x.x ...
+```
+
+## 4. Run a command directly
+
+```{ .bash .copy }
+docker run --rm <image-id> hello
+```
+
+```{ .console .no-copy }
+Hello, world!
+```
+
+This runs the command inside the activated environment without starting an interactive shell, similar to `flox activate -- hello`.
+
+## 5. Tag and push
+
+Build with a specific tag:
+
+```{ .bash .copy }
+flox containerize --tag v1 --runtime docker
+```
+
+Then push to a registry:
+
+```{ .bash .copy }
+docker tag <image-name>:v1 myregistry.example.com/myproject:v1
+docker push myregistry.example.com/myproject:v1
+```
+
+## 6. Customize the image
+
+You can configure OCI metadata for the container image in the `[containerize.config]` section of your manifest.
+Run `flox edit` and add:
+
+```toml
+[containerize.config]
+working-dir = "/app"
+exposed-ports = ["8080/tcp"]
+cmd = ["hello"]
+```
+
+See the [`flox containerize` reference][containerize-man] for the full list of configuration options, including `user`, `volumes`, `labels`, and `stop-signal`.
+
+## Next steps
+
+- Read about [how containerize differs from thin containers](../tech.md) at a technical level
+- Learn about [thin containers](../thin-containers/intro.md) for faster iteration without image rebuilds
+- See the full [`flox containerize` reference][containerize-man] for all CLI options
+
+[containerize-man]: ../../man/flox-containerize.md
+[flox-install]: ../../install-flox/install.md
+[docker-install]: https://docs.docker.com/get-docker/
+[podman-install]: https://podman.io/docs/installation

docs/containers/containerize/intro.md

@@ -0,0 +1,47 @@
+---
+title: "Containerize"
+description: "Build traditional OCI container images from Flox environments."
+---
+
+# Containerize
+
+[`flox containerize`][containerize-man] exports a Flox environment as a standard OCI container image with all dependencies baked in at build time.
+Unlike [thin containers](../thin-containers/intro.md) and [Imageless Kubernetes](../imageless-kubernetes/intro.md), the resulting image does **not** use Flox or the Nix store at runtime --- it's a conventional container image that can be pushed to any registry and run anywhere.
+
+## Consider thin containers first
+
+Before reaching for `flox containerize`, consider whether [thin containers](../thin-containers/intro.md) or [Imageless Kubernetes](../imageless-kubernetes/intro.md) would be a better fit for your use case.
+With `flox containerize`, you give up several advantages of the thin-container model:
+
+| | Thin Containers | Containerize |
+| --- | --- | --- |
+| **Image rebuilds** | Not needed --- environments resolve at startup | Required on every environment change |
+| **Caching** | Shared Nix store across all environments | Each image is self-contained |
+| **Image size** | Tiny base image; packages from shared store | All packages baked into the image |
+| **FloxHub management** | Centralized --- changes propagate automatically | Frozen at build time |
+| **Iteration speed** | ~5s startup (after first run) | Rebuild + push + pull cycle |
+
+## When to use `flox containerize`
+
+`flox containerize` is the right choice when deploying to infrastructure that **requires standard container images** and cannot support a mounted Nix store volume:
+
+- Container registries and orchestrators that expect self-contained images (e.g., AWS ECS, Docker Swarm, cloud functions)
+- Environments where volume mounts are restricted or unavailable
+- Distribution to users who don't have Flox or a Nix store
+
+## What you still get
+
+Even though `flox containerize` uses the traditional model, the images it produces are superior to hand-written Dockerfiles:
+
+- **Fully pinned** --- the same lockfile that drives your development environment drives the image, so you get identical software down to the Git revisions of upstream source repositories
+- **Cross-platform** --- define one environment, build images for multiple architectures
+- **Reproducible** --- the same lockfile always produces the same image contents
+- **Configurable** --- set OCI metadata (ports, volumes, labels, user, working directory) via the manifest's `[containerize.config]` section
+
+## Next steps
+
+Follow the [getting started guide](getting-started.md) to build your first container image from a Flox environment.
+
+See the [`flox containerize` reference][containerize-man] for the full list of CLI options and manifest configuration.
+
+[containerize-man]: ../../man/flox-containerize.md

docs/imageless-kubernetes/config.md → docs/containers/imageless-kubernetes/config.md

@@ -24,7 +24,7 @@ flox auth token \
 ```
 
 !!! note "Token expiry"
-    Tokens generated with `flox auth token` are associated with your user account and will expire 1 month from when they were issued. For a more robust alternative see [Machine Access Tokens for Organizations](../concepts/organizations.md#machine-access-tokens).
+    Tokens generated with `flox auth token` are associated with your user account and will expire 1 month from when they were issued. For a more robust alternative see [Machine Access Tokens for Organizations](../../concepts/organizations.md#machine-access-tokens).
 
 !!! note "Flox CLI version"
     The user creating the token via `flox auth token` will need at least version 1.7.6 of the Flox CLI.
@@ -106,7 +106,7 @@ By default, Imageless Kubernetes pods start in `run` mode. `run` mode is intende
 
 The `flox.dev/activate-mode` annotation can be used to configure the mode, which may be useful for applications such as running CI jobs in Flox-enabled pods.
 
-See the [`options.activate.mode`](../man/manifest.toml.md#options) option in the manifest for more details on modes.
+See the [`options.activate.mode`](../../man/manifest.toml.md#options) option in the manifest for more details on modes.
 
 ```yaml
 apiVersion: v1
@@ -200,6 +200,6 @@ metadata:
 The difference from `skip-containers` is that while `skip-containers-exec` containers will have their main process run from the Flox environment, commands run via `kubectl exec` or equivalent will be run outside of it. This option is best used when you want the container's main workload to run in the Flox environment, but need exec commands (for debugging, health checks, or auxiliary tasks) to run in the base container environment without Flox.
 
 [intro]: ./intro.md
-[floxhub]: ../concepts/floxhub.md
-[flox_auth]: ../man/flox-auth.md
-[generations]: ../concepts/generations.md
+[floxhub]: ../../concepts/floxhub.md
+[flox_auth]: ../../man/flox-auth.md
+[generations]: ../../concepts/generations.md

docs/imageless-kubernetes/examples/gitlab-ci.md → docs/containers/imageless-kubernetes/examples/gitlab-ci.md

@@ -66,4 +66,4 @@ Since the CI environment doesn’t rely on a container image, updates are instan
 
 [gitlab-k8s-docs]: https://docs.gitlab.com/runner/executors/kubernetes/
 [config]: ../config.md
-[floxhub]: ../../concepts/floxhub.md
+[floxhub]: ../../../concepts/floxhub.md

docs/imageless-kubernetes/install/self-managed.md → docs/containers/imageless-kubernetes/install/self-managed.md

@@ -150,6 +150,6 @@ Once the nodes have Flox and the shim installed, you are ready to create pods us
 A sample `Pod` manifest is available in the [Introduction][intro-section], but any Kubernetes resource that creates a pod (e.g. `Deployment`) can be used by setting the `runtimeClassName` parameter to `flox`.
 
 [intro-section]: ../intro.md
-[install-flox]: ../../install-flox/install.md
+[install-flox]: ../../../install-flox/install.md
 [shim-installer]: https://hub.flox.dev/flox/containerd-shim-flox-installer
 [runtime-class]: https://kubernetes.io/docs/concepts/containers/runtime-class/

docs/imageless-kubernetes/install/uninstall.md → docs/containers/imageless-kubernetes/install/uninstall.md

@@ -59,4 +59,4 @@ rm /usr/local/bin/containerd-shim-flox-v2
 And finally, uninstall Flox from each node by following the instructions from the [Uninstall Flox][uninstall-flox] page.
 
 [self-managed]: ./self-managed.md
-[uninstall-flox]: ../../install-flox/uninstall.md
+[uninstall-flox]: ../../../install-flox/uninstall.md

docs/imageless-kubernetes/install/upgrading.md → docs/containers/imageless-kubernetes/install/upgrading.md

@@ -31,4 +31,4 @@ after which, all new pods will be created with the new shim version.
 Existing Flox pods will only use the new version once they are restarted.
 
 [eks]: ./eks.md
-[install-flox]: ../../install-flox/install.md
+[install-flox]: ../../../install-flox/install.md

docs/imageless-kubernetes/intro.md → docs/containers/imageless-kubernetes/intro.md

@@ -84,6 +84,6 @@ Imageless Kubernetes is also currently available for:
 
 See the [installation][install-section] for more details on installing Imageless Kubernetes in your cluster.
 
-[generations-concept]: ../concepts/generations.md
+[generations-concept]: ../../concepts/generations.md
 [install-section]: ./install/eks.md
 [examples-section]: ./examples/kind-demo.md

docs/containers/intro.md

@@ -0,0 +1,63 @@
+---
+title: "Flox in Containers"
+description: "Run Flox environments inside containers for isolation, reproducibility, and fast iteration."
+---
+
+# Flox in Containers
+
+Flox environments can run inside containers, giving you isolated, reproducible execution with the same packages you use during development.
+The key difference from traditional container workflows is that packages live in a shared [Nix store][nix-store] mounted into the container rather than baked into the image.
+This eliminates image rebuilds, enables shared caching across environments, and dramatically speeds up iteration.
+
+## Choosing an approach
+
+Flox offers three ways to run environments in containers.
+The first two use the thin-container model described above; the third is a traditional approach included for compatibility.
+
+### Thin Containers (Docker / Podman) {: .recommended }
+
+<!-- markdownlint-disable-next-line MD036 -->
+**Recommended for: local development, CI/CD, AI agent sandboxing**
+
+Run any FloxHub environment in a Docker or Podman container with a single command, or use the `--sandbox` flag on `flox activate` for a seamless experience.
+Packages are cached in a shared Nix store volume, so only the first run is slow (~30-60s); subsequent runs start in ~5 seconds.
+
+No image builds. No Dockerfiles. No image pipelines.
+
+[Get started with Thin Containers :material-arrow-right:](thin-containers/intro.md){ .md-button }
+
+### Imageless Kubernetes
+
+<!-- markdownlint-disable-next-line MD036 -->
+**Recommended for: production Kubernetes workloads**
+
+Run Kubernetes pods backed by Flox environments instead of container images.
+A containerd shim resolves environments from FloxHub at pod startup, giving you centralized management, an audit trail of changes, and the same software you used during development.
+
+[Get started with Imageless Kubernetes :material-arrow-right:](imageless-kubernetes/intro.md){ .md-button }
+
+### Containerize
+
+<!-- markdownlint-disable-next-line MD036 -->
+**Traditional approach: when standard OCI images are required**
+
+[`flox containerize`][containerize-man] builds a self-contained OCI image from a Flox environment with all dependencies baked in.
+Unlike thin containers and Imageless Kubernetes, the resulting image does **not** use Flox or the Nix store at runtime --- it's a conventional container image.
+
+Use this only when deploying to infrastructure that requires standard container images and cannot support the thin-container model.
+The trade-offs are significant:
+
+- Images must be rebuilt every time the environment changes
+- No shared caching --- each image is self-contained
+- Larger image sizes compared to the thin-container approach
+- No centralized management via FloxHub
+
+[Get started with Containerize :material-arrow-right:](containerize/intro.md){ .md-button }
+
+## How it works
+
+All three approaches build on the same foundation: Flox environments backed by Nix.
+See [How it works](tech.md) for the technical details of how packages are resolved and mounted inside containers.
+
+[nix-store]: https://nix.dev/manual/nix/latest/store/
+[containerize-man]: ../man/flox-containerize.md