Contribute to Tascarrel

The source repository uses Nix for its toolchain and packaging environment:

nix develop

Run Focused Checks

For a Rust change, format and check the affected package:

cargo fmt --all -- --check
cargo test -p tascarrel-host
cargo clippy -p tascarrel-host --all-targets -- -D warnings

Use full checks only for cross-cutting changes:

cargo test --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
nix flake check

The frontend/ package scripts provide its type checks, linting, and production build.

Develop the Frontend in a Pod

Start Vite in the Tascarrel pod and publish its port:

pnpm run dev
podctl http publish --title "Tascarrel frontend" 5174

In the packaged frontend, trust the published route as the Tascarrel frontend, then open it from the Network view. Tascarrel’s host daemon (hostd) installs a route-scoped HttpOnly cookie and exposes the same-origin API bridge below /.tascarrel/api/v1. The development frontend discovers that bridge without an API-root environment override.

Build Guest Images

nix build .#packages.x86_64-linux.vm-image
nix build .#packages.aarch64-linux.vm-image

Guest boot, device, and packaging changes require architecture-relevant checks; host-only unit tests do not exercise the VM boundary.

Build a Distribution

nix build .#tascarrel

The complete distribution embeds the immutable NixOS store image, Linux kernel, initrd, guest services, pod tools, the bundled Tasci agent, and compiled UI in the native server executable. nix build .#tascarrel-cli builds the unembedded development server and administrative client.

Build the Linux desktop launcher and its bundled server for Nix with:

nix build .#tascarrel-desktop

Build a self-contained AppImage for Debian, Ubuntu, and other Linux distributions without Nix:

nix build .#tascarrel-desktop-appimage

The AppImage embeds the Nix store closure needed by the desktop launcher and server. The target machine does not need a Nix installation or matching /nix/store paths. It does need FUSE 3, which Debian and Ubuntu provide in the fuse3 package, and enabled user namespaces.

At startup, Tascarrel verifies and extracts the payload below $TASCARREL_HOME/state/payloads/<sha256>/.

Override Guest Binaries

Replace packaged Linux guest binaries for one VM boot:

nix develop --command cargo build \
  -p tascarrel-guest \
  -p tascarrel-podd \
  -p tascarrel-podctl \
  -p tasci-exec
nix run .#host -- --local-binaries "$PWD/target/debug"

The directory is mounted read-only using virtiofs on Linux, with 9p as a Linux fallback and as the macOS transport. Replacement binaries must target Linux and the guest architecture. The directory must contain executable tascarrel-guest, tascarrel-podd, podctl, and tasci-exec files.