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, 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:

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

macOS

brew install python@3.12

Verify:

python3 --version

Windows

Download and install Python from python.org, or use Chocolatey:

choco install python --version=3.12.0

Verify:

python --version

Linux

sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip

Verify:

python3 --version

Set up a virtual environment

venv

python3 -m venv .venv

macOS / Linux

source .venv/bin/activate

Windows

.venv\Scripts\Activate.ps1

uv

If you prefer uv for faster package management:

# 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

Install Truffile

With your environment activated:

pip install truffile

Verify the installation:

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

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.

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:

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.

Before connecting from Truffile, onboard your device through the Symphony desktop client. Download Symphony from the 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.

Next steps

Start a Convo

Connect, open a Convo thread, and talk to the stateful on-device agent.

Build your first app

Learn how Truffle apps are structured and scaffold one with truffile create.