🍄‍🟫 Truffile

Python SDK/CLI for Truffle devices.

What It Does

  • discovers and connects to your Truffle (scan, connect, disconnect)
  • copies bundled agent resources into your workspace (load)
  • validates and deploys apps from truffile.yaml (validate, deploy)
  • manages installed apps (list apps, delete)
  • talks to inference directly (models, chat)

Start making your Own Apps

  • app schema and validation: truffile/truffile/schema/app_config.py
  • schedule parsing: truffile/truffile/schedule.py
  • deploy planning + builder flow: truffile/truffile/deploy/builder.py
  • generated TruffleOS protos vendored in: truffile/truffle/
  • bundled example apps live under truffile/app-store/
  • bundled Codex skills live under truffile/skills/

truffile.yaml defines:

  • metadata (name, description, type)
  • process (cmd, working_directory, environment)
  • files to upload
  • optional run/build commands
  • background schedule policy (for BG apps)

App Types and Runtime Model

Apps can be:

  • foreground (fg): exposes MCP tools that tasks/agents can call during active execution
  • background (bg): runs on schedule and emits context for proactivity, enabling the device to trigger actions and write/update memory
  • both (fg + bg): one app package can provide MCP tools and scheduled context emission

How to think about it:

  • FG path is tool-serving: app process is used as a callable capability surface (MCP)
  • BG path is context/proactivity: scheduled runs feed the proactive agent with fresh signals
  • Proactivity can take actions and persist memory based on BG outputs

In practice:

  • use fg when you need direct tool invocation from tasks
  • use bg when you need periodic monitoring, summaries, or event-driven context
  • use both when the same app should both expose tools and continuously feed proactivity/memory

Core Commands

truffile scan
truffile connect <device>
truffile create [app_name]
truffile load all
truffile validate [app_dir]
truffile deploy [app_dir]
truffile deploy --dry-run [app_dir]
truffile list apps --json
truffile delete <app-name>
truffile models
truffile chat

truffile create scaffolds a hybrid app starter with:

  • truffile.yaml (foreground + background process config)
  • copy-file steps for generated *_foreground.py and *_background.py
  • icon.png copied from docs/Truffle.png (deploy requires an icon)

truffile load all copies bundled agent-readable resources into your current workspace:

  • ./truffile/skills/ for CLI/chat/infer/app-creation skills
  • ./truffile/examples/ for bundled example apps such as ArXiv, Exa, Notion, Obsidian, Viator, WHOOP, and Home Assistant

Use truffile load skills or truffile load examples to copy only one group.

Obsidian Bridge Workflow

For a local Obsidian vault on your laptop, truffile can run a small host-side bridge and deploy a bundled foreground app to the device:

truffile obsidian attach --vault ~/Documents/abd-vault
truffile obsidian serve
truffile obsidian deploy

Use truffile obsidian status to inspect the saved bridge configuration. The bridge stores a scoped bearer token in the local truffile state file and the bundled app uses that token to read, write, list, and search notes in the configured vault.

In truffile chat, runtime controls are slash commands (not launch flags):

  • /help for all chat commands
  • /config to show current chat config
  • /reasoning on|off
  • /stream on|off
  • /json on|off
  • /tools on|off
  • /max_tokens <int>, /temperature <float|off>, /top_p <float|off>, /max_rounds <int>
  • /models to switch model
  • /attach <path-or-url> to attach an image for the next user message (local path or http(s) URL)
  • /system <text|clear>
  • /mcp connect <http(s)://...>, /mcp tools, /mcp status, /mcp disconnect

Inference Interfaces

Direct IF2:

  • list models: GET /if2/v1/models
  • chat completions: POST /if2/v1/chat/completions

CLI wrappers:

  • truffile models
  • truffile chat (streaming by default)

Proto Sync

Refresh vendored protos from firmware repo:

./scripts/sync_protos.sh

Development Loop

The supported app development loop is CLI-first:

truffile create my-app --path ./apps
truffile validate ./apps/my-app
truffile deploy --dry-run ./apps/my-app
truffile deploy ./apps/my-app

After deploy, use truffile chat to attach the app to a task and exercise its tools with the on-device agent. Use truffile delete to remove test apps from the connected device.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.21)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for deepshard from gravatar.com deepshard Avatar for deepshard-abd from gravatar.com deepshard-abd

License

MIT

Requires

Python >=3.12

Provides Extra

dev

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

truffile-0.3.8.tar.gz (1.2 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

truffile-0.3.8-py3-none-any.whl (1.4 MB view details)

Uploaded Python 3

File details

Details for the file truffile-0.3.8.tar.gz.

File metadata

  • Download URL: truffile-0.3.8.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for truffile-0.3.8.tar.gz
Algorithm Hash digest
SHA256 f1020be3d721a29bbac348722edc552e1ed096954c19456b4382d90eb06e87a6
MD5 17f513f9784a15f0d4c93dd16bb6bb4c
BLAKE2b-256 ecd81505b481adba6e496bfa16eebf6099c1d08ef7492038bda0e8f41a34003d

See more details on using hashes here.

Provenance

The following attestation bundles were made for truffile-0.3.8.tar.gz:

Publisher: publish-truffile.yml on deepshard/pyfw

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file truffile-0.3.8-py3-none-any.whl.

File metadata

  • Download URL: truffile-0.3.8-py3-none-any.whl
  • Upload date:
  • Size: 1.4 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for truffile-0.3.8-py3-none-any.whl
Algorithm Hash digest
SHA256 6d307dd9e4464ca7f877d90ac0e7e33ebd8b2f093811d6bfcceedf74817e314d
MD5 5f3ddcf50f752108b324f24ae756be15
BLAKE2b-256 b7c1a7a3083e8f9d7137e217977c392b75bf2b6f3a4230343a00a0a64c9ae925

See more details on using hashes here.

Provenance

The following attestation bundles were made for truffile-0.3.8-py3-none-any.whl:

Publisher: publish-truffile.yml on deepshard/pyfw

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

This release

0.3.8 This release

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.35

2 files

0.1.33

2 files

0.1.31

2 files

0.1.29

2 files

0.1.27

2 files

0.1.25

2 files

0.1.23

2 files

0.1.21

2 files

0.1.19

2 files

0.1.17

2 files

0.1.14

2 files

0.1.12

2 files

0.1.11

2 files

0.1.8

2 files

0.1.7

2 files

Pre-release

0.1.dev4

2 files

Pre-release

0.1.dev1

2 files

0.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page