Skip to content
Get Started

Sharing environments

flox makes it easy to seamlessly develop on multiple machines with no additional configuration: if you update an environment on one machine, you can pull those changes to that environment to any numbers of machines via git.

If you haven't already, please install flox. You will also need a GitHub account to follow this tutorial.

Use two machines with internet access.

The machines don't have to be two physical machines, you can easily use two docker images with flox:

docker run --pull always --rm -it ghcr.io/flox/flox

1. flox gh auth login - authenticate with GitHub

flox environments are synchronized by way of shared git repositories.

This tutorial uses your GitHub account to create and use your own personal floxmeta repository.

You will only need to authenticate once unless you explicitly logout by way of the gh app.

$ flox gh auth login
? What account do you want to log into?  [Use arrows to move, type to filter]
> GitHub.com
  GitHub Enterprise Server
? What is your preferred protocol for Git operations?  [Use arrows to move, type to filter]
  HTTPS
> SSH
? Upload your SSH public key to your GitHub account?  [Use arrows to move, type to filter]
> /home/USER/.ssh/id_ed25519.pub
  Skip
? Title for your SSH key: (GitHub CLI) flox CLI
? How would you like to authenticate GitHub CLI?  [Use arrows to move, type to filter]
> Login with a web browser
  Paste an authentication token
! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...
Opening in existing browser session.
✓ Authentication complete.
- gh config set -h github.com git_protocol https
  ✓ Configured git protocol
  ✓ Logged in as USER

2. flox push - Push the environments to GitHub

Environments are shared by way of the flox push command, and flox will automatically walk you through the process of creating your floxmeta repository the first time you push an environment.

You will only need to create the floxmeta repository once.

$ flox install -e demo cowsay fortune # (1)!
Installed 'cowsay', 'fortune' package(s) into 'default' environment.

$ flox push -e demo # (2)!
flox uses git to store and exchange metadata between users and machines.

Where would you like to host your 'floxmeta' repository?
1) github.com
2) gitlab.com
3) bitbucket.org
4) other
Choose git server by number: 1
Great, let's start by getting you logged into github.com.
Success! You are logged into github.com as USER.

What is your preferred protocol for Git operations?
1) https
2) ssh+git
Choose protocol by number: 1

confirm git URL for storing profile metadata: https://github.com/USER/floxmeta
Already on 'x86_64-linux.demo'
Your branch is up to date with 'origin/x86_64-linux.demo'.
Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 8 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 1.49 KiB | 1.49 MiB/s, done.
Total 8 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), done.
To https://github.com/USER/floxmeta
 * [new branch]      origin/x86_64-linux.demo -> x86_64-linux.demo

  1. We will create a demo environment with two packages: cowsay and fortune.

  2. When prompted, please answer "1" to both prompts as shown in the example output below.

3. flox pull - Pull the environments from GitHub

On a second machine where we also have flox installed, we will pull our demo environment that we created in previous section.

You don't need to own an environment to use it, as long as you have access to the floxmeta repository you can pull the environment. This way teams and organizations can share access the same way as they would share access to their repositories.

Change visibility of floxmeta repository to public

In the previous step our floxmeta repository was created as we pushed our demo environment. By default the floxmeta repository is private. In order to avoid authentication issues in our docker container below, I suggest we make floxmeta repository public.

Head to Settings -> General and look for the Change visibility button somewhere at the bottom. Follow the instructions to make the floxmeta repository public.

If you wish to make your environments private in the future you can always turn floxmeta repository back to being private.

$ docker run --pull always --rm -it ghcr.io/flox/flox # (1)!

(docker) $ flox pull -e USER/demo # (2)!
remote: Enumerating objects: 17, done.
remote: Counting objects: 100% (17/17), done.
remote: Compressing objects: 100% (11/11), done.
remote: Total 17 (delta 1), reused 16 (delta 1), pack-reused 0
Unpacking objects: 100% (17/17), 5.42 KiB | 924.00 KiB/s, done.
From https://github.com/USER/floxmeta
 * [new branch]      aarch64-linux.demo -> origin/aarch64-linux.demo
 * [new branch]      floxmain           -> origin/floxmain
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To /root/.cache/flox/meta/USER
 * [new branch]      aarch64-linux.demo -> aarch64-linux.demo
flox: created directory '/root/.local/share/flox/environments/USER'

(docker) $ flox activate -- sh -c "fortune | cowsay"
/ Q: How did you get into artificial   \
| intelligence? A: Seemed logical -- I |
\ didn't have any real intelligence.   /
 --------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

(docker) $ exit
$

  1. As our second machine we are just going to spin up a docker container.

  2. We are pulling demo the environment that we pushed at the previous section.

Where to next?