> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install fxtr from a local checkout and verify the setup with an optional example.

**TODO: Update these installation instructions once packaging and distribution are finalized.**

<Note>
  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.
</Note>

## Prerequisites

* [uv](https://docs.astral.sh/uv/) 0.12.2 or newer, git (or jj), and
  [pnpm](https://pnpm.io/).
* 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:

  ```bash theme={null}
  uv sync --all-packages --all-extras
  pnpm install
  ```

## 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](/fxtr/first-experiment) walks through that path from project creation
to writing and running your own code.

<Steps>
  <Step title="Start Postgres">
    fxtr keeps every job, result, and cache entry in Postgres. The checkout's `postgres_env/`
    runs a local server in a container:

    ```bash theme={null}
    cd postgres_env
    cp .env.example .env
    docker compose up -d --wait    # or: podman compose up -d --wait
    cd ..
    ```

    It listens on port `55433`, with user, password, and database all named `fxtr`.
  </Step>

  <Step title="Create the example project">
    From the checkout:

    ```bash theme={null}
    uv run fxtr new ~/code/fxtr-example --example
    ```

    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:

    ```bash theme={null}
    cd ~/code/fxtr-example
    (cd views && pnpm install)
    ```
  </Step>

  <Step title="Connect it to the database">
    From the new project:

    ```bash theme={null}
    cd ~/code/fxtr-example
    uv run fxtr init --database-url postgresql+asyncpg://fxtr:fxtr@localhost:55433/fxtr
    ```

    This writes `fxtr.local.toml`, which records where this machine reaches the database and is
    never committed, and creates the project's tables.
  </Step>

  <Step title="Commit and launch the example">
    Every launch records the commit it runs, so commit first:

    ```bash theme={null}
    git add . && git commit -m "A new fxtr project"
    uv run python launch.py
    ```

    The included code greets three guests; you do not need to write any experiment code for
    this check:

    ```text theme={null}
    job f0d6b1ac-a781-4b93-a571-edef402ad131: running
    watch it at http://127.0.0.1:8000/#job=f0d6b1ac-a781-4b93-a571-edef402ad131
    job f0d6b1ac-a781-4b93-a571-edef402ad131: succeeded
      result: bafyreid7ea3tcab7lyxpgpyisaiwphsyqygdjnynpupdgqpk3tc2iixxsi
    Hello, Ada!
    Hello, Alan!
    Hello, Grace!
    ```
  </Step>

  <Step title="Open the viewer">
    ```bash theme={null}
    uv run fxtr view
    ```

    This serves the experiment viewer at `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.
  </Step>
</Steps>

## What's in the example project

```text theme={null}
pyproject.toml            the project, its dependency on fxtr, and [tool.fxtr]
README.md                 how to run it
launch.py                 runs the experiment as a job
src/fxtr_example/
    experiment.py         an entity type, a step, and a workflow: an example to replace
views/                    renderers that customize how the viewer shows your data
.agents/skills/           guides for coding agents, linked from .claude/skills/
```

`[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

<CardGroup cols={2}>
  <Card title="Your first experiment" icon="flask" href="/fxtr/first-experiment">
    Write an experiment of your own, step by step.
  </Card>

  <Card title="Core concepts" icon="book" href="/fxtr/concepts/overview">
    How projects, steps, workflows, jobs, and arrays fit together.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.