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 run `truffile scan` and `truffile connect <device-name>`. During `truffile connect`, I can enter my User ID from Symphony Settings, then 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, my 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:

python -m pip install --upgrade truffile

Before connecting from Truffile, onboard your device through the Symphony desktop client. Download Symphony from the client overview and complete device onboarding. When you run truffile connect, enter your User ID from Symphony Settings, then approve the new session on your Truffle device.

​

Build and manage apps

Truffile 0.3.35 adds native installation, account setup, developer uploads, and friendly account selection. Use current device firmware for uploaded updates and replacements; unsupported firmware is detected before those operations.

truffile connect 6272
truffile create my-app --path ./apps
truffile validate ./apps/my-app
truffile deploy ./apps/my-app
truffile deploy ./apps/my-app --update

Read deployment and accounts and authentication for updates, replacement, OAuth, API keys, and permission controls. After upgrading, refresh previously exported skills with truffile load skills --force only if you intend to overwrite those exported copies; keep your app source separately.

​

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.