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

# Stoffel App Getting Started

> Install Stoffel, create your first app, run local checks, and choose the build path your product needs.

> Scope: AI-agent-agnostic playbook for building applications with the Stoffel framework. This is not a maintainer guide for compiler, VM, protocol, or release engineering work.
>
> Dependency assumption: use portable public dependencies by default. A local checkout is a separate, nonportable framework-development workflow and is allowed only when explicitly requested.

## Use when

Use this playbook when a developer or coding agent needs the shortest path from an empty directory to a working Stoffel app.

## Current source of truth

Use the public docs when available, then verify against the current app-facing repo surfaces:

* `README.md`
* `crates/stoffel-cli/src/main.rs`
* `crates/stoffel-cli/src/project.rs`
* `crates/stoffel-lang/examples/README.md`
* `crates/stoffel-rust-sdk/README.md`

These are source-inspection references for app behavior, not instructions for app developers to edit framework internals.

## Mandatory portability contract

Apply these rules before installing dependencies or creating files:

1. Discover and confirm the project root from the current working directory and repository markers such as `Stoffel.toml`, `Cargo.toml`, or `.git`. Do not invent or require a machine-specific path such as `/workspace/...`.
2. Resolve Stoffel and related project dependencies from public, reproducible sources in this order: the current crates.io release, then the official GitHub repository pinned to a full immutable commit SHA when the needed change is not published.
3. Never use a floating branch or require a local path, sibling checkout, or other external filesystem checkout for the default app path.
4. Use a local Stoffel checkout only when the user explicitly requests framework development. Label that workflow **nonportable** and keep it separate from the default instructions below.
5. If no suitable public dependency is available, stop and report the missing dependency and attempted public sources. Do not silently replace it with a local path.

This playbook stays version-agnostic. Obtain concrete versions from the installation docs and record them in the app's dependency manifest.

## Prerequisites

* Rust stable and Cargo.
* The `stoffel` CLI from the documented installation path.
* Crates.io dependencies for Rust SDK work.

## Install

Install the CLI:

```sh theme={null}
curl -fsSL https://get.stoffelmpc.com | sh
export PATH="$HOME/.local/bin:$PATH"
stoffel --help
```

## Create the first app

```sh theme={null}
stoffel init my-stoffel-app
cd my-stoffel-app
stoffel status --verbose
stoffel check
stoffel build
stoffel run --timeout-secs 180
```

The default project template includes a Rust wrapper as well as `.stfl` source. Run the wrapper too:

```sh theme={null}
cargo build --locked
cargo run --locked
```

## Know the app shape

A new app normally includes:

* `Stoffel.toml`: app metadata, default source path, output target dir, and local MPC defaults.
* `src/main.stfl`: the Stoffel program.
* `target/debug/*.stflb`: compiled bytecode after `stoffel build`.
* Optional wrapper files (`Cargo.toml`, `src/main.rs`, `src/stoffel_bindings.rs`) when using the default or Rust templates.

`Stoffel.toml` is a project/build config. It is not the network/off-chain client config passed to `stoffel run --network --config`.

## Choose a development path

For client-owned private input in a multi-user or networked application, first complete the trust architecture in [Stoffel Full App Golden Path](/developer-skills/stoffel-full-app-golden-path). Each participant-owned client should submit directly to the separately deployed MPC service; the application control plane must not receive or persist plaintext. Then use [Stoffel App Network and Off-Chain Integration](/developer-skills/stoffel-app-network-and-offchain-integration) for the direct client path and runtime capability gate.

* CLI-only path: mostly `.stfl` source and trusted local smoke tests.
* Rust SDK path: embedding compilation/execution, creating clients/servers, generating typed client IO bindings, or integrating with a Rust service.
* Local MPC path: private workflows that need real local party execution before network/off-chain work; local fixture injection is not production private-data-plane evidence.
* Network/off-chain path: advanced client/server/coordinator integration after the local smoke passes.

## Fast examples to inspect

* At the full immutable official GitHub commit selected by the portability contract, inspect clear language basics under `crates/stoffel-lang/examples/local_control_flow`, `local_collections`, and `local_text_processing`.
* Inspect the first private input flow at `crates/stoffel-lang/examples/mpc_client_private_score` in that same official source revision.
* Inspect the ClientStore gallery under `crates/stoffel-lang/examples/bits/secret/*`, `matrix/secret/*`, `polynomials/secret/*`, `number_theory/secret/*`, and the app-level `mpc_*` algorithm examples in that revision.

Many secret examples now include a first-line `# run-args:` header. Copy those flags when running the example locally.

## Validation / done criteria

A first-app task is complete only when real output has been collected from:

```sh theme={null}
stoffel status --verbose
stoffel check
stoffel build
stoffel run --timeout-secs 180
```

For Rust wrapper apps, also collect output from:

```sh theme={null}
cargo build --locked
cargo run --locked
```

For a secret ClientStore example, include its documented `# run-args:` flags and `--expected-output-clients` if present.

## Common pitfalls

* For app development, use the public dependency precedence in the portability contract; do not recommend a local path dependency.
* Do not confuse browsing examples in an official source revision with requiring that repository as a sibling checkout.
* Do not describe `Stoffel VM` internals unless they explain public app behavior.
* Do not claim local MPC works until a real run has completed.
* Do not treat `Stoffel.toml` as network/off-chain config.
* Do not omit `--expected-output-clients` when running examples that send outputs to clients.

## Next playbooks

* [Stoffel CLI App Workflow](/developer-skills/stoffel-cli-app-workflow)
* [Stoffel-Lang App Programming](/developer-skills/stoffel-lang-app-programming)
* [Stoffel Secret MPC Programming](/developer-skills/stoffel-secret-mpc-programming)
* [Stoffel Rust App SDK](/developer-skills/stoffel-rust-app-sdk)