Serverbox Onboarding

ServerBox onboarding

ServerBox is a Flutter app (iOS, Android, macOS, Linux, Windows, watchOS) for managing Linux, BSD and Windows servers: status charts, SSH terminal, SFTP, containers, processes, systemd. The repository is a monorepo:

A server can use SSH, a monitor agent's HTTP API, or both. Each configured transport contributes its own capabilities; see references/principles.md.

Work out which question this is first

People arrive at this project from two directions, and the answers barely overlap. Read the one reference that matches, not all of them.

Mixed asks are common and the wording rarely says which is which. "The terminal button disappeared" is the agent's capability model (monitor-deploy.md), not a bug. "flutter pub get fails right after cloning" is almost always uninitialised submodules (dev-setup.md). When it is genuinely ambiguous, ask whether they are running ServerBox or working on it.

The repository outranks this skill

Versions, ports and command names drift; a skill file that quietly disagrees with the repo is worse than no skill. Inside a checkout, prefer these:

Outside a checkout the reference files here are the fallback. Say so when you are answering from them — the numbers below were true when this was written and nothing keeps them current.

scripts/check-env.sh reports what is installed against what the repo asks for, and changes nothing. Run it before diagnosing a build failure by hand; most first-run failures are one of the four things it checks.

The commands that cover most of it

make deps        # flutter pub get
make run         # flutter run
make gen         # build_runner + gen-l10n — after touching any annotated model
make analyze     # flutter analyze lib test integration_test
make test        # flutter test
cargo test --workspace          # parser, native sampler, FFI, monitor
make monitor-dev                # agent API on :3770 + panel dev server on :3000
make build PLATFORM=<android|ios|macos|linux|windows>

Values as of writing: Flutter >= 3.44.9, Dart SDK >= 3.11.0, Rust pinned to 1.97.1 for the FFI crate, Node 24 for the monitor panel and the docs site.

What costs people an afternoon

Each of these has bitten someone. The reason matters more than the fix, because the symptom rarely names the cause.

• Initialise submodules before fetching Dart dependencies. packages/* are path dependencies, so flutter pub get fails on a missing directory rather than on anything that mentions submodules: git submodule update --init --recursive.
• Rust is not optional, even for flutter run. hook/build.dart compiles crates/sbm_ffi into every app build as a code asset. No Rust toolchain, no app.
• flutter_rust_bridge is pinned to the same prerelease in two files — pubspec.yaml and crates/sbm_ffi/Cargo.toml. When they disagree, RustLib.init throws at startup and the message does not mention versions.
• Regenerate after changing an annotated model (freezed, json_serializable, riverpod, hive): make gen. Never hand-edit *.g.dart, *.freezed.dart or anything under lib/src/rust/.
• Never run a formatter. The formatting in this codebase is deliberate, and a reformat buries the actual change in noise.
• Do not start a second flutter run when the user already has the app running from their IDE. Two debug builds compete for the same window and you end up inspecting an instance nobody is looking at. Hot reload through the dart MCP server instead (CLAUDE.md has the sequence).
• flutter clean deletes the out-of-tree iSH engine build and leaves a checkout that looks fine, so the next iOS build dies in the linker on three missing .a files. Only affects a checkout that turned SBM_ISH on.

Answering "how does X work"

The deep explanations already exist in docs/src/content/docs/principles/ (architecture, ssh, sftp, terminal, state) — 250 to 400 lines each, and worth reading rather than paraphrasing from memory. references/principles.md is the map: what each one answers, plus the handful of design decisions that explain the most behaviour, so you can route in one step instead of grepping.

When the answer is about code rather than design, read the code. The docs describe intent; lib/data/provider/, lib/data/store/ and monitor/src/api/ are what actually runs.

Reference files