Flox workshop with examples

A tiny HTTP API that serves quotes - used to demonstrate Flox environments.

Lab 0: Explore our example app

This is a simple Go application that serves quotes over HTTP.

Take a look at the code:

cat main.go

It loads quotes from a JSON file and serves them on port 3000.

Let's try to run it:

go run main.go quotes.json
# command not found: go

Go is not installed. We need a development environment.

Lab 1: Your first Flox environment

Let's fix that with Flox:

# Create a minimal Flox environment
flox init --bare

# Install Go
flox install go

# Activate the environment
flox activate

# Now it works!
go run main.go quotes.json

In another terminal, test it:

curl http://localhost:3000/ | jq
curl http://localhost:3000/quotes | jq
curl http://localhost:3000/quotes/0 | jq

Lab 2: Running a database

Our app can also load quotes from Redis. Let's set that up as a service.

Install Redis:

flox install redis

Configure Redis as a service by editing the manifest:

flox edit

Add the following to your manifest.toml:

[services.redis]
command = "redis-server --port $REDISPORT"

[vars]
REDISPORT = "6379"

[profile]
common = """
  alias load_quotes='redis-cli -p $REDISPORT SET quotesjson "$(cat quotes.json)"'
"""

Now start the services and activate:

flox activate --start-services

Load quotes into Redis:

load_quotes

Run the app with Redis:

go run main.go redis

Test it:

curl http://localhost:3000/quotes | jq

Lab 3: Reusing environments (composition)

Instead of configuring everything ourselves, we can reuse environments from FloxHub. Let's replace our manifest with includes.

Edit the manifest:

flox edit

Replace the contents with:

version = 1

[install]

[vars]

[include]
environments = [
    { remote = "flox/go" },
    { remote = "flox/redis" }
]

That's it! The flox/go environment provides Go, and flox/redis provides Redis pre-configured as a service.

Reactivate to pick up the changes:

flox activate --start-services

Load quotes and run:

redis-cli -p $REDISPORT SET quotesjson "$(cat quotes.json)"
go run main.go redis

Environment composition lets you build on top of curated, reusable building blocks instead of starting from scratch every time.

Lab 4: Prepare for production (build & publish)

Let's package our app for distribution.

Edit the manifest:

flox edit

Add a build section:

[build.quotes-app]
command = """
  mkdir -p $out/bin $out/share
  cp quotes.json $out/share/
  go build -trimpath -o $out/bin/quotes-app main.go
"""

Build the package:

flox build

Test the built binary:

./result-quotes-app/bin/quotes-app ./result-quotes-app/share/quotes.json

Now publish it to FloxHub:

flox publish

Others can now use your published package in their environments.

Your app is now available as a reusable package on FloxHub!

Bonus Lab: Flox & AI

Flox integrates with AI coding assistants through MCP (Model Context Protocol).

Claude Code Setup

Install the Flox MCP server (into your default environment):

flox install flox/flox-mcp-server

Or activate it directly:

flox activate -r flox/flox-mcp-server

Install the Flox plugin in Claude Code:

/plugin marketplace add flox/flox-agentic
/plugin install flox@flox-agentic

The plugin includes 7 specialized skills:

• flox-environments - Package management and environment setup
• flox-services - Service configuration and orchestration
• flox-builds - Building and packaging applications
• flox-containers - Docker/Podman containerization
• flox-publish - Publishing packages to FloxHub
• flox-sharing - Environment composition and collaboration
• flox-cuda - GPU/CUDA development (Linux only)

Other Editors

For Cursor, add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "flox": {
      "command": "flox-mcp"
    }
  }
}

Now your AI assistant understands Flox! Try asking it to:

• Create a new Flox environment for a Python project
• Add a service to your manifest
• Help debug environment issues
• Build and publish a package

AI + reproducible environments = superpower.

Bonus Lab 2: Nix Expression Builds

Lab 4 used a manifest build (Bash script). For guaranteed reproducibility, you can use a Nix expression instead.

Create the Nix package file:

mkdir -p .flox/pkgs

Create .flox/pkgs/quotes-app-nix.nix:

{ buildGoModule, lib }:

buildGoModule {
  pname = "quotes-app-nix";
  version = "1.0.0";

  src = ../../.;

  vendorHash = null;  # Uses go.sum for dependencies

  postInstall = ''
    mkdir -p $out/share
    cp ${../../quotes.json} $out/share/quotes.json
  '';

  meta = {
    description = "A tiny HTTP API that serves quotes";
    mainProgram = "quotes-app-go";
  };
}

Make sure all files are tracked by git:

git add .flox/pkgs/

Build with Nix:

flox build .#quotes-app-nix

Test the built binary:

./result/bin/quotes-app-go ./result/share/quotes.json

Note: Package names must be unique. We use quotes-app-nix to avoid conflict with the manifest build quotes-app from Lab 4.

Why Nix expressions?

• Builds are isolated in a sandbox (no host system leakage)
• Purely functional - same inputs always produce same outputs
• Better for CI/CD and production deployments
• Access to the full Nix ecosystem of build helpers

---

Reference

Usage

# Load from a JSON file
go run main.go quotes.json

# Load from Redis
go run main.go redis

Redis Setup

When using Redis as source, populate the data first:

redis-cli SET quotesjson "$(cat quotes.json)"

Configure Redis port via environment variable (default: 6379):

REDISPORT=6379 go run main.go redis

Testing

go test -v ./...