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

# Installation

> Install the Truffile SDK to use Convo and deploy apps to your Truffle

## Prerequisites

* Python 3.12 or higher
* A Truffle¹ device
* The [Symphony desktop client](/client/overview), with your device already onboarded

## Agent setup prompt

If you want Codex, Claude Code, or another coding agent to set up Truffile for you, paste this prompt into the agent from the directory where you want the environment created:

```text theme={null}
Set up Truffile for me in this directory.

Use explicit CLI commands and explain what you are doing as you go.

Requirements:
- Make sure Python 3.12 or newer is available. Prefer `python3.12` when present; otherwise use the newest `python3`/`python` that is >=3.12.
- Prefer `uv` if it is installed. If `uv` is not installed, use the standard library `venv` module.
- Create a local virtual environment named `.venv`.
- Activate/use that virtual environment for all Python and pip commands.
- Install Truffile with `pip install truffile`; if it is already installed, make sure it is upgraded to the latest version.
- Verify the install with `truffile --help`.
- Run `truffile load all` so the bundled skills and example apps are copied into this workspace under `./truffile/skills` and `./truffile/examples`.
- Do not require a Truffle device to finish setup. If no device is connected yet, tell me that I first need to onboard my Truffle through the Symphony desktop client at https://docs.truffle.net/client/overview, then get my User ID from Symphony > Settings, then run `truffile scan` and `truffile connect <device-name> --user-id <user-id>`. During `truffile connect`, I must approve the new session on my Truffle device.

After `truffile load all`, inspect the local resources before giving me the onboarding:
- Read `./truffile/skills/truffile-cli/SKILL.md` for scan/connect/create/validate/deploy/list/delete/obsidian.
- Read `./truffile/skills/truffile-convo/SKILL.md` for the stateful on-device agent.
- Read `./truffile/skills/truffile-infer/SKILL.md` for raw model inference and MCP testing.
- Read `./truffile/skills/truffle-app-creator/SKILL.md` for creating or porting Truffle apps.
- Skim the example app manifests under `./truffile/examples/*/truffile.yaml` so you know the foreground, background, auth, and install-step patterns available.
- Run `truffile --help`, `truffile deploy --help`, `truffile convo --help`, and `truffile infer --help` so you know the CLI surface.

When setup is complete, give me a short onboarding that covers:
- that connecting requires a Symphony-onboarded Truffle, the User ID from Symphony > Settings, and device approval during `truffile connect`
- how to connect a Truffle device
- how to use Convo with the on-device agent, including that old Task histories are not visible after the one-way cutover
- how to use Truffile as an inference endpoint/client
- how to create, validate, deploy, list, and delete apps
- where the copied skills and example apps live in this workspace
- links to the docs:
  - https://docs.truffle.net/client/overview
  - https://docs.truffle.net/sdk/installation
  - https://docs.truffle.net/sdk/cli
  - https://docs.truffle.net/sdk/convo
  - https://docs.truffle.net/sdk/convo-automation
  - https://docs.truffle.net/sdk/building-apps
- End by asking whether I want to start by making a Truffle app.
```

The prompt works because Truffile is CLI-first: every core workflow has explicit arguments, and `truffile load all` gives the agent local skills and example apps to read before it starts building.

## Install Python

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install python@3.12
    ```

    Verify:

    ```bash theme={null}
    python3 --version
    ```
  </Tab>

  <Tab title="Windows">
    Download and install Python from [python.org](https://www.python.org/downloads/), or use Chocolatey:

    ```powershell theme={null}
    choco install python --version=3.12.0
    ```

    Verify:

    ```powershell theme={null}
    python --version
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    sudo apt update
    sudo apt install python3.12 python3.12-venv python3-pip
    ```

    Verify:

    ```bash theme={null}
    python3 --version
    ```
  </Tab>
</Tabs>

## Set up a virtual environment

<Tabs>
  <Tab title="venv">
    ```bash theme={null}
    python3 -m venv .venv
    ```

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        source .venv/bin/activate
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        .venv\Scripts\Activate.ps1
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="uv">
    If you prefer [uv](https://github.com/astral-sh/uv) for faster package management:

    ```bash theme={null}
    # install uv if you don't have it
    curl -LsSf https://astral.sh/uv/install.sh | sh

    # create and activate a venv
    uv venv
    source .venv/bin/activate   # macOS / Linux
    # or
    .venv\Scripts\Activate.ps1  # Windows
    ```
  </Tab>
</Tabs>

## Install Truffile

With your environment activated:

```bash theme={null}
pip install truffile
```

Verify the installation:

```bash theme={null}
python -c 'from truffile.transport.client import TruffleClient; print("ok")'
truffile convo --help
```

The import should print `ok`, and the help output should list the Convo prompt,
targeting, action, and output flags. The released wheel already contains its
generated `truffle.*_pb2` bindings.

### Installing from a source checkout

<Warning>
  The repo-root `truffle/` generated package is deliberately gitignored in the
  source repository. Before an editable install or wheel build, copy it from the
  generated Python tree in a matching `pyfw` checkout. Do not rely on an
  untracked `scripts/` helper.
</Warning>

```bash theme={null}
git clone https://github.com/deepshard/truffile.git
cd truffile
PYFW_CHECKOUT=/path/to/pyfw
cp -a "$PYFW_CHECKOUT/python/truffle" ./truffle

python3.12 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -c \
  'from truffile.transport.client import TruffleClient; print("ok")'
.venv/bin/truffile convo --help
```

The editable install imports the staged ignored package in place. If you are
building a distributable wheel, record the selected protocol source revision
and build only after staging the generated package:

```bash theme={null}
git -C "$PYFW_CHECKOUT" rev-parse HEAD > truffle/PROTOCOL_SHA
.venv/bin/python -m pip wheel --no-deps --wheel-dir dist .
```

That wheel embeds the generated bindings, type stubs, and `PROTOCOL_SHA`, so a
normal installation from the wheel is self-contained.

<Note>
  Before connecting from Truffile, onboard your device through the Symphony desktop client. Download Symphony from [the client overview](/client/overview), complete device onboarding, then copy your User ID from **Symphony → Settings**. `truffile connect` will ask for that User ID and then you must approve the new session on your Truffle device.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Start a Convo" icon="comments" href="/sdk/convo">
    Connect, open a Convo thread, and talk to the stateful on-device agent.
  </Card>

  <Card title="Build your first app" icon="wrench" href="/sdk/building-apps">
    Learn how Truffle apps are structured and scaffold one with `truffile create`.
  </Card>
</CardGroup>