How to install the development toolchain
← All revisions
Track-B documentation wave: how-to category — schema-conformant restructure of 2 guides + heavy R1/DP6 redaction of collect-location-intelligence-data (internal vendor rosters/production counts removed)
@@ -7,10 +7,15 @@ category: how-to index_group: getting-started content_type: how-to type: how-to quality: complete status: active audience: "Engineers (hands on keyboard); new contributors" last_edited: 2026-08-06 editor: pointsav-engineering paired_with: install-toolchain.es.md research_trail: sources: [pointsav-monorepo rust-toolchain.toml, bin/commit-as-next.sh, identity/ store layout] verification_method: "verified against the real rust-toolchain.toml pin and the commit-as-next.sh pre-commit gate already documented in read-write-totebox-archives.md" --- The platform codebase is a Rust workspace. The development toolchain consists of the Rust compiler and standard Cargo build tools, plus the workspace commit helper that enforces staging-tier identity and SSH commit signing. This guide covers installing both, verifying the installation, and making your first test build. @@ -23,82 +28,84 @@ For the broader workspace architecture, see [[totebox-orchestration-development] - SSH access to your workspace VM - A shell session on that VM ## Step 1: Install the Rust toolchain ## Purpose The workspace uses a pinned Rust toolchain version specified in `rust-toolchain.toml` at the monorepo root. Install `rustup`, the Rust toolchain manager, if it is not already present: Install the pinned Rust toolchain, confirm it builds and tests the workspace cleanly, and verify the commit helper and SSH signing key are ready — the full set of preconditions for making a first commit in a monorepo archive. ``` curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` ## Procedure After installation, source the environment file or open a new shell session. Rustup reads `rust-toolchain.toml` automatically when you enter a directory with one — no explicit version selection is needed. 1. **Install the Rust toolchain.** The workspace uses a pinned Rust toolchain version specified in `rust-toolchain.toml` at the monorepo root. Install `rustup`, the Rust toolchain manager, if it is not already present: ## Step 2: Verify the Rust installation ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` Run a version check from within the monorepo clone: After installation, source the environment file or open a new shell session. Rustup reads `rust-toolchain.toml` automatically when you enter a directory with one — no explicit version selection is needed. ``` cd ~/Foundry/clones/<your-archive>/pointsav-monorepo cargo --version rustc --version ``` 2. **Verify the Rust installation.** Run a version check from within the monorepo clone: Both commands should print the pinned version from `rust-toolchain.toml`. If rustup reports that the toolchain is not installed, run `rustup show` to trigger the automatic install of the pinned version. ```bash cd ~/Foundry/clones/<your-archive>/pointsav-monorepo cargo --version rustc --version ``` ## Step 3: Run a baseline build Both commands should print the pinned version from `rust-toolchain.toml`. If rustup reports that the toolchain is not installed, run `rustup show` to trigger the automatic install of the pinned version. Build the full workspace to confirm the toolchain is working end to end: 3. **Run a baseline build.** Build the full workspace to confirm the toolchain is working end to end: ``` cargo build ``` ```bash cargo build ``` A clean build on first run downloads and compiles all dependencies and may take several minutes. Subsequent builds are incremental. If the build fails with a missing dependency, install the named system library via the package manager (`apt-get install <lib>` on Debian/Ubuntu) and re-run. A clean build on first run downloads and compiles all dependencies and may take several minutes. Subsequent builds are incremental. If the build fails with a missing dependency, install the named system library via the package manager (`apt-get install <lib>` on Debian/Ubuntu) and re-run. ## Step 4: Verify the commit helper 4. **Verify the commit helper.** The workspace commit helper (`~/Foundry/bin/commit-as-next.sh`) requires a working SSH agent with the staging-tier signing key loaded. Direct `git commit` is blocked by a pre-commit gate — all commits must go through the helper. The workspace commit helper (`~/Foundry/bin/commit-as-next.sh`) requires a working SSH agent with the staging-tier signing key loaded. Direct `git commit` is blocked by a pre-commit gate — all commits must go through the helper. Verify the helper is reachable: Verify the helper is reachable: ```bash ls ~/Foundry/bin/commit-as-next.sh ``` ``` ls ~/Foundry/bin/commit-as-next.sh ``` Verify an SSH key is loaded: Verify an SSH key is loaded: ```bash ssh-add -l ``` ``` ssh-add -l ``` If no keys are listed, add your staging identity's key: If no keys are listed, add your staging identity's key: ```bash ssh-add ~/Foundry/identity/<your-identity>/<your-key> ``` ``` ssh-add ~/Foundry/identity/<your-identity>/<your-key> ``` Staging-tier teams typically alternate commit authorship across two or more identities automatically — check your workspace's identity store for the exact names in use. Staging-tier teams typically alternate commit authorship across two or more identities automatically — check your workspace's identity store for the exact names in use. 5. **Run tests.** Confirm the test suite passes before starting work: ## Step 5: Run tests ```bash cargo test ``` Confirm the test suite passes before starting work: ## Expected outcome ``` cargo test ``` `cargo build` and `cargo test` both complete cleanly on the pinned toolchain version, the commit helper script is reachable, and an SSH key is loaded in the agent — the workspace is ready for a first commit. ## Verification All tests should pass on a clean clone. A test failure before any local changes indicates either a stale clone or a build environment issue — check `git status` and compare the HEAD commit against the upstream staging branch. ## Key takeaways ## Rollback Toolchain installation has no destructive side effect to roll back. If `rustup` was installed in error, remove it with `rustup self uninstall`; this does not affect the monorepo clone itself. - The toolchain version is pinned in `rust-toolchain.toml`; rustup reads it automatically - `cargo build` / `cargo test` / `cargo clippy` / `cargo fmt` are always allowed without approval - All commits use `commit-as-next.sh`; direct `git commit` is blocked at the pre-commit gate - An SSH key must be loaded in the agent before the commit helper can sign commits ## Next steps - [[read-write-totebox-archives]] — the full read/write flow for working in an archive - [[open-first-totebox-session]] — the full session startup sequence after toolchain setup ## See also - [[totebox-orchestration-development]] — the session architecture this toolchain supports - [[open-first-totebox-session]] — the full session startup sequence after toolchain setup - [[pair-a-new-device]] — how a device gets paired to the workspace in the first place - [[read-write-totebox-archives]] — the full read/write flow for working in an archive