fxtr is not published to a package index yet. A project depends on a local checkout of the
fxtr repository by path. The commands below run from that checkout unless they say otherwise.
Prerequisites
- uv 0.12.2 or newer, git (or jj), and pnpm.
- A container runtime with Compose, such as Docker or Podman, for a local Postgres server. Any Postgres server works if you already have one.
-
The fxtr checkout, set up from its root:
Verify the installation with an example
The following steps create and run a complete greeting example. The--example flag includes
the experiment code and its launcher, so you can check that your installation works before
writing an experiment of your own.
Without --example, fxtr new creates an empty project with no experiment or launcher.
Your first experiment walks through that path from project creation
to writing and running your own code.
1
Start Postgres
fxtr keeps every job, result, and cache entry in Postgres. The checkout’s It listens on port
postgres_env/
runs a local server in a container:55433, with user, password, and database all named fxtr.2
Create the example project
From the checkout:This writes a uv project with a complete greeting experiment in
src/fxtr_example/experiment.py, a launch.py that runs it, and greeting renderers for
the viewer. It also runs git init and uv sync, and prints the next steps.Install the example’s renderer dependencies before committing the project:3
Connect it to the database
From the new project:This writes
fxtr.local.toml, which records where this machine reaches the database and is
never committed, and creates the project’s tables.4
Commit and launch the example
Every launch records the commit it runs, so commit first:The included code greets three guests; you do not need to write any experiment code for
this check:
5
Open the viewer
http://127.0.0.1:8000/ and opens it in your browser.
Open the link the launcher printed to see the job’s graph: the guest list, the greet step
mapped over it, and each greeting it produced.What’s in the example project
[tool.fxtr] modules in pyproject.toml lists the modules that define your steps and
workflows. When you add an experiment module, add it there too.
Next steps
Your first experiment
Write an experiment of your own, step by step.
Core concepts
How projects, steps, workflows, jobs, and arrays fit together.