POC and demo scripts

Five demos, each with commands that appear in the Flox docs, a success criterion and a time-box: a first environment, sharing it on FloxHub, services, a container image, and imageless Kubernetes on a local cluster. Since 2026-10-20, install, upgrade and resolve need a free FloxHub login; search, show and activating an environment with a valid lockfile stay public. Time-boxes on this page are suggestions, not Flox figures.

This page is drawn from https://flox.dev/docs/flox-5-minutes, https://flox.dev/docs/install-flox/install, https://flox.dev/docs/concepts/authentication, https://flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know/, https://flox.dev/docs/man/flox-init, https://flox.dev/docs/man/flox-activate, https://flox.dev/docs/man/flox-containerize, https://flox.dev/docs/tutorials/sharing-environments, https://flox.dev/docs/imageless-kubernetes/examples/kind-demo and https://flox.dev/docs/concepts/services, all checked 2026-11-04.

Before you start

• Install Flox. The install page documents curl -fsSL https://get.flox.dev | sh, which picks the macOS .pkg, a Debian or Ubuntu .deb, or a Fedora or RHEL .rpm (https://flox.dev/docs/install-flox/install). Flox supports macOS and Linux on x86_64 and ARM (https://flox.dev/docs/flox-5-minutes).
• Log in first. Run flox auth login and sign in with GitHub, Google or GitLab (https://flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know/). FloxHub accounts are free (https://flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know/).
• What needs a login since 2026-10-20. flox install, flox upgrade (including --dry-run), flox run, and any command that has to lock the environment because manifest.lock is missing or a catalog package changed, including flox activate, flox edit, flox list, flox services, flox build and flox containerize (https://flox.dev/docs/concepts/authentication). flox push and flox publish already needed it (https://flox.dev/docs/concepts/authentication).
• What stays public. flox search and flox show, flox pull of a public environment, flox activate with a current lockfile, flox build with a current lockfile, and edits to [vars], [hook], [profile] or [services] (https://flox.dev/docs/concepts/authentication). flox init also works without a sign-in, but in a Node.js, Python or Go project its package suggestions need one (https://flox.dev/docs/concepts/authentication).
• Offline or air-gapped POCs. A lockfile removes the need to resolve but not the need to obtain packages, so prepare the locked environment and make the packages available locally first (https://flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know/).

POC success criteria (agree on these first)

Ask the customer to pick measures before you start. Suggested, and all the customer’s to change:

• A person who has never used Flox gets a working environment in the time-box below, from a repo or from FloxHub (https://flox.dev/docs/flox-5-minutes).
• Two machines, ideally one macOS and one Linux, get the same package versions from the same lockfile (https://flox.dev/docs/flox-5-minutes).
• The customer names one number they will compare before and after, for example setup time or environment-related questions. Flox publishes no benchmark to borrow [verify] (https://flox.dev/case-studies/).
• A named owner decides on the close-out date. See the close-out checklist below.

Demo 1: a first environment (10 minutes)

Goal: show that an environment is a directory with a manifest. Needs a login for the install step (https://flox.dev/docs/concepts/authentication).

mkdir myproject && cd myproject
flox init
flox search ripgrep
flox show ripgrep
flox install ripgrep
flox list
flox activate -c "rg --version"

• flox init creates a .flox directory in the project (https://flox.dev/docs/concepts/flox-vs-containers) and tries to detect languages in the directory (https://flox.dev/docs/man/flox-init).
• flox search and flox show find packages and list versions (https://flox.dev/docs/flox-5-minutes).
• flox activate -c CMD runs a shell command string in a subshell started in the activated environment (https://flox.dev/docs/man/flox-activate). flox activate -- CMD runs a command in the environment without entering a subshell and without running profile scripts (https://flox.dev/docs/man/flox-activate).
• Success: rg is on the path inside the environment and absent outside it. Say: “Nothing was installed to your system.” Check this yourself first; the docs describe isolation in subshells but your host may differ [verify] (https://flox.dev/docs/concepts/flox-vs-containers).

Demo 2: share it and reproduce it (10 minutes)

Goal: another machine gets the same environment. Share with git, then with FloxHub (https://flox.dev/docs/tutorials/sharing-environments).

git add .flox && git commit -m "sharing flox environment"
# on another machine, after git clone:
flox activate
# or via FloxHub:
flox auth login
flox push
flox pull youruser/myproject
flox activate -r youruser/myproject

• Committing .flox lets another developer clone the repo and run flox activate to get the same package versions (https://flox.dev/docs/tutorials/sharing-environments).
• flox push sends the environment to FloxHub, and flox pull youruser/example-project fetches it elsewhere (https://flox.dev/docs/tutorials/sharing-environments). flox activate -r some_user/myenv activates an environment pushed to FloxHub (https://flox.dev/docs/man/flox-activate).
• Pulling or activating a private environment needs a login; a public one does not, unless it adds your system to the environment (https://flox.dev/docs/concepts/authentication).
• Note the docs say only environment owners can push edits to their environments (https://flox.dev/docs/tutorials/sharing-environments). Organizations are a paid Team feature (https://flox.dev/docs/concepts/organizations).
• Success: the second machine reports the same package versions in flox list.

Demo 3: services (8 minutes)

Goal: a database or worker that starts with the environment. Use the sample project (https://flox.dev/docs/flox-5-minutes).

git clone https://github.com/flox/flox-in-5min.git
cd flox-in-5min
flox activate
flox services start
flox services status
flox services logs --follow
flox services stop

• The sample environment includes a stopwatch service, and services are defined in the [services] section of the manifest (https://flox.dev/docs/flox-5-minutes).
• Services stop automatically when you exit the environment (https://flox.dev/docs/flox-5-minutes). flox activate --start-services starts them on activation (https://flox.dev/docs/man/flox-activate).
• The flox services commands count among those that need a login if the lockfile is missing (https://flox.dev/docs/concepts/authentication). Whether this sample repo ships a current lockfile is not stated [verify] (https://flox.dev/docs/flox-5-minutes).
• Success: status shows Running, logs stream, and the process is gone after exit.

Demo 4: export a container image (8 minutes)

Goal: the same environment as an OCI image. Needs Docker or Podman on macOS (https://flox.dev/docs/man/flox-containerize).

flox containerize --runtime docker
docker run -it <image>

• flox containerize --runtime docker loads the image into Docker, and Flox splits each dependency into its own layer by default (https://flox.dev/docs/tutorials/sharing-environments).
• Running interactively launches a bash subshell with your packages and variables set; running non-interactively runs a command, like flox activate -- (https://flox.dev/docs/man/flox-containerize).
• --file writes the image to a file, --tag and --label set metadata, and -m dev|run selects the activation mode (https://flox.dev/docs/man/flox-containerize).
• Success: the container runs the same commands as the activated environment. Image size comparisons against the customer’s Dockerfile are the customer’s to measure; Flox’s headline figure is a vendor claim [verify] (https://flox.dev/kubernetes/).

Demo 5: imageless Kubernetes on kind (15 minutes)

Goal: a pod that names a FloxHub environment instead of an image. Needs Flox and a FloxHub login (https://flox.dev/docs/imageless-kubernetes/examples/kind-demo).

git clone https://github.com/flox/flox-kind-demo.git &&
cd flox-kind-demo &&
flox activate -- just up
curl localhost:3000/quotes/0
just down

• This starts a local kind cluster and deploys a web server backed by Redis, and the token is copied into a Kubernetes secret for the shim (https://flox.dev/docs/imageless-kubernetes/examples/kind-demo).
• The key lines are runtimeClassName: flox and the annotation flox.dev/environment: "flox/quotes-app"; the container image is the placeholder flox/empty:1.0.0 (https://flox.dev/docs/imageless-kubernetes/examples/kind-demo).
• Updating means flox publish then flox upgrade -r flox/quotes-app, and a pod restart pulls the latest generation (https://flox.dev/docs/imageless-kubernetes/examples/kind-demo).
• For real clusters: each node needs Flox, the containerd shim and containerd 1.7 or newer (https://flox.dev/docs/imageless-kubernetes/install/self-managed). EKS and self-managed Kubernetes are listed as available (https://flox.dev/docs/imageless-kubernetes/intro).
• Success: curl returns a quote and the customer can point to the manifest lines that replaced an image build.

Optional: CI

The docs list flox/install-flox-action and flox/activate-action, which runs a command inside the environment (https://flox.dev/docs/tutorials/ci-cd). A committed manifest.lock lets CI activate without credentials; otherwise use a service account token in FLOX_FLOXHUB_TOKEN (https://flox.dev/blog/flox-catalog-login-requirement-what-you-need-to-know/).

POC close-out checklist

• Re-read the success criteria with the customer and record the measured result against their number.
• List which commands needed a login, and confirm that account and token handling is acceptable (https://flox.dev/docs/concepts/authentication).
• Note which plan the pilot used and which features the next step needs: the Free plan has 3 private FloxHub envs and Team lists unlimited team FloxHub envs (https://flox.dev/pricing/).
• Send the customer the exact commands and the repo or environment they ran, so they can repeat the POC alone.