AI Environment Assistant

Русский · English · Release notes 0.2.0

Cross-platform guided setup for employees who are new to AI tools. The primary verified deliverable is a portable Windows x64 ZIP. Linux x64 and Intel macOS are native-tested technical previews; macOS arm64 is an unsigned cross-build preview.

The application scans the machine, refreshes trusted catalogs and current vendor versions before showing the main UI, explains compatibility, detects existing software, and executes only the plan confirmed by the user. The tool catalog is stored outside the executable and can be extended without changing the UI.

The source is available under the Apache License 2.0 and the privacy policy.

Current capabilities

• Windows 10 22H2 / Windows 11 x64, Ubuntu/Debian, and macOS scanning;
• portable self-contained Windows ZIP, Linux tar.gz and .deb, and macOS app ZIP packaging;
• reproducible VMware exact-ZIP gate under real standard-user and administrator security contexts, including the fail-closed UAC boundary;
• complete Russian/English UI and light/dark themes;
• OS, CPU, RAM, storage, GPU/VRAM, user privilege, and VPN-interface scan;
• safe allowlisted outbound preflight: registry/API HTTPS through the system or corporate proxy and explicit direct TCP ports only for declared protocols; before installation the UI identifies the unreachable host, port, purpose, and DNS, proxy 407, TLS, timeout, or blocking failure class;
• discovery of known CLI tools, desktop AI applications, Ollama, llama.cpp, LM Studio, KoboldCpp, and non-PATH managed installations;
• isolated local-model profiles for Codex, OpenCode, Cline CLI, and Continue CLI without overwriting the user's primary configuration;
• hardware-aware portable KoboldCpp selection: official CUDA asset for NVIDIA or CPU/Vulkan asset otherwise, with GitHub SHA-256 and version verification;
• per-quantization local-model guidance using reliably detected dedicated VRAM, unified memory, or RAM, with exact weight size and an explicit warning that KV-cache demand is runtime-dependent;
• mandatory pre-UI refresh of the signed tool catalog, agent versions, Hugging Face GGUF metadata/quantizations, official benchmark tiers, and runtime releases;
• separately signed Ollama/llama.cpp/llmster source catalog with verified offline cache and one effective source across checker, installer, and UAC resume;
• separately signed cloud-provider metadata covering every CloudAi card; verified links/OpenUrl actions and required API endpoints are applied to the real network preflight before scan and again during UAC resume;
• signed corporate package routing for HTTPS artifacts, npm, uv, WinGet, Homebrew, APT, Git, container/Ollama registries, SHA-256-pinned VSIX packages, and WSL root filesystems, with explicit vendor/prefer/require modes and pre-install mirror endpoint checks; offline mode uses content-addressed artifacts, WSL rootfs payloads, and local npm/uv caches;
• a content-addressed offline bundle whose manifest hash is bound by the signed source catalog and whose payload hashes are rechecked before use;
• immutable Hugging Face revision, artifact size, LFS SHA-256, gated-model, and resumable-download checks;
• GGUF search across model, publisher, base model, license, task, tags, and quantization, plus independent publisher/license/task/size/advertised-context filters that keep hidden models out of the download plan;
• managed GGUF inventory, verified re-use, configurable model storage, and safe copy-and-switch migration;
• versioned llama.cpp and portable Ollama installation from allowlisted official releases with digest checks;
• Debian/Ubuntu headless LM Studio (llmster) installation from official metadata with mandatory SHA-512 verification;
• explicit model/runtime selection, compatibility preflight, Ollama import, LM Studio import, and loopback-health-checked llama.cpp launch profiles;
• desktop catalog for ChatGPT/Codex, Claude Desktop, Antigravity 2.0 and IDE, Cursor, Windsurf, Kiro, OpenClaw Companion, Hermes Desktop, Jan, Open WebUI Desktop, and ComfyUI Desktop;
• CLI/ADE catalog for Codex, Claude Code, Gemini, Antigravity, Hermes, OpenClaw, GitHub Copilot, Cline, Cursor Agent, OpenCode, Qwen Code, Kimi Code, goose, Aider, the official modular DeepSeek Harness developer preview, Orca ADE, Google Jules Tools, Anthropic Platform CLI, GitHub Agentic Workflows, the official rlms library, and a separately warned RLM CLI;
• twelve beginner setup profiles for Codex, Claude, Google, major, Russian and Chinese browser assistants, research and documents, cloud media creation, local desktop AI, local model serving, local image generation, and local document/OCR/speech processing; profiles preselect a reviewable set and never bypass plan confirmation;
• user-scoped portable Git, VS Code, current Node.js LTS, and managed Python fallback when administrator rights are unavailable;
• safe portable VS Code updates from Microsoft metadata with SHA-256, exact-version verification, rollback, and preservation of the Windows portable data directory;
• Hermes Desktop resolution from the official Nous Research page, strict asset-host allowlisting, and required Nous Research Inc. Authenticode validation before silent user-scope installation; an HTTP 403 response opens the official guided manual path instead of bypassing verification;
• typed MCP configuration for detected Codex, Claude, Gemini, Antigravity, Hermes, OpenClaw, Cursor, Cline, and Copilot agents;
• exact-ID VS Code extension installation and verification for GitHub Copilot, Cline, and Continue;
• pinned-commit Agent Skill installation and the official Claude Hookify plugin through its user-scoped marketplace CLI;
• pinned official Gemini Security extension and Cline TypeScript Navigation plugin with exact-revision checkout and post-install verification;
• separate provider-login cards for Claude, Gemini, Copilot, Anthropic CLI, GitHub CLI, and Jules. Vendor CLIs own the interactive flow and tokens; published status commands are used for verification;
• Windows Credential Manager storage for GitHub PAT and Context7 key. A managed secret runner injects each value only into the child MCP process environment, not the agent configuration or command line;
• repository cloning with exact origin/HEAD validation and preservation of unrelated or incomplete existing directories;
• a reviewable plan, sequential execution, secret redaction, and mandatory post-install rescan;
• administrator elevation only for privileged actions. Declining UAC preserves an administrator instruction file and continues independent user-scoped work; resumable journals are accepted only after a fresh catalog refresh and scan;
• per-component installation strategy: system-integrated applications use the normal vendor channel and UAC where required, while verified portable and user-scoped runtimes remain available to both administrators and standard users; neither account type is treated as the exceptional case;
• WinGet reboot-required outcomes are reported without automatic reboot.

Development

.NET SDK 10 is required.

dotnet restore AiForBeginners.slnx --disable-build-servers -m:1
dotnet build AiForBeginners.slnx -c Release --no-restore --disable-build-servers -m:1
dotnet test AiForBeginners.slnx -c Release --no-build --disable-build-servers -m:1
dotnet run --project src\AiForBeginners.App\AiForBeginners.App.csproj -c Release

Windows package

Prebuilt packages for all three platforms are on the Releases page. They are not signed — the project holds no code-signing certificate — so Windows shows a SmartScreen "Unknown publisher" prompt. Verify downloads against SHA256SUMS.txt.

powershell -ExecutionPolicy Bypass -File scripts\publish.ps1

The result is artifacts/AIEnvironmentAssistant-win-x64.zip, containing a self-contained single-file executable and the editable catalog.

publish.ps1 creates a release candidate. Verified ZIPs use scripts/release-windows.ps1, which enforces tests, CycloneDX SBOM, SLSA provenance, artifact hashing, and a clean packaged scanner run. See production release.

Linux and macOS packages

Run on the target operating system:

scripts/publish-linux.sh linux-x64
scripts/publish-macos.sh osx-arm64

The Linux script creates tar.gz and .deb packages. The macOS script creates an app ZIP and signs it when APPLE_SIGNING_IDENTITY is available. CI uses .github/workflows/release.yml for the platform matrix.

Headless scanner check:

./AiForBeginners.App --scan-only --lang=en

Headless installation of selected recipes still performs the mandatory startup scan and metadata refresh first:

.\AiForBeginners.App.exe --install-tools playwright-mcp,fetch-mcp --lang=en

Required secret inputs are read only from process environment variables named AEA_INPUT_<INPUT_ID> (for example, AEA_INPUT_CONTEXT7_API_KEY), never from command-line arguments. Plans requiring elevation remain interactive-only.

Extending the catalog

Edit catalog/tools.json. Mutable cloud-provider links and required API checks live in catalog/provider-metadata.json and can be delivered as a separate ECDSA-signed envelope. Only typed, allowlisted actions documented in docs/CATALOG.md are accepted. Arbitrary manifest-provided PowerShell, cmd, or shell commands are intentionally not supported. See Signed provider catalog for schema and publishing instructions.

New tools enter an advisory research layer first. It checks typed official npm, PyPI, GitHub, and WinGet sources and produces lifecycle evidence for CI, but it cannot modify the signed catalog. See Catalog research for the command and the manual candidate-to-recipe gate.

The --scan-only JSON includes ScanReport.Network for an IT support ticket. It contains exact endpoints, ports, purposes, results, the selected proxy, and PAC/WPAD diagnostics without credentials. The UI can temporarily apply a manual http(s)://host:port proxy to this process and rerun the checks; credentials in the URI are rejected. The preflight does not enumerate the local network or probe arbitrary ports. See docs/NETWORK-PREFLIGHT.md.

Current limitations

• Account registration remains on official vendor sites. OAuth/login runs in the vendor CLI's interactive window. Gemini, Copilot, and Jules currently expose no separate stable non-interactive status probe, so the app reports vendor-flow completion without reading the token store.
• GitHub PAT and Context7 keys are not persisted in the user environment: Windows uses Credential Manager, macOS uses Keychain, and Linux uses Secret Service through secret-tool. Only the child MCP process receives the value. Linux requires libsecret-tools and an unlocked desktop keyring.
• A user-scoped plan can resume after a crash or app close from its last confirmed action boundary. The next launch offers resume, later, or delete; secret input values are never written to the journal.
• A separate ECDSA-signed corporate policy snapshot defines allow/block rules for tools, Hugging Face publishers and licenses, plus role-aware recommendations. Advisory warns; Enforce blocks selection in both UI and headless flows. See Corporate policy.
• Docker Desktop and some system installers still require administrator help.
• Successful post-install detection for large Windsurf and Kiro downloads has not been observed in the current clean VM because both official CDNs timed out twice with WinGet 0x80072ee2; package resolution, bounded retry, and honest failure guidance are verified.
• The Hermes signed bootstrap is verified, but its CDN returned HTTP 403 from the clean VM and its secondary payload could not complete there; the app therefore uses the documented manual fallback for that network condition.
• Linux .deb install/upgrade/uninstall, Linux arm64, physical Apple hardware, Gatekeeper after browser download, Developer ID signing, notarization, and Apple Silicon runtime execution remain unverified.
• The preflight supports the system proxy/PAC and a process-local manual proxy. Core artifact/npm/uv/WinGet/Git/VSIX/Homebrew/APT/WSL mirrors, container and Ollama registries, Claude plugin marketplaces, and the offline bundle are implemented through signed exact routes.
• Non-Windows corporate secret-store adapters remain a future corporate enhancement. The release already contains SBOM and provenance evidence.

Documentation

Each document below has a Russian mirror named <name>.ru.md, except the release-status record, which is a maintainer document.

• Contributing
• Security
• Privacy policy
• Third-party notices
• Install on Linux
• Install on macOS
• Architecture
• Product specification
• Catalog
• Catalog research
• Signed installation catalog
• Signed cloud-provider catalog
• Signed runtime source catalog
• Signed package sources and offline bundles
• Corporate policy
• Network preflight
• Elevation
• Model catalog
• Local runtimes
• Portability
• Release status

Support author

BTC: bc1q3frrup5neh7nhfg944etu2agd4j9u0vg3jyee6

ETH(Arbitrum): 0x43B349d8Cea83215D707EBa3bc35e9917f746b0a

TRX: THSzvy49KNeqRjXsGkurh2A5G4avV4RgN4

XRP: rLWZjS3DMupC4ZdXCX3BVYn4dEtC3iNhgy

SOL: 3xwfybxJ6Tz5t6pjBBkL5yYQCZo6wfbv932UNA4ThdP8

ADA: addr1q926ys75jp5wn2pv32a3t8r8pdhr7w02v0t9j4a8pmg0ruww5rlkctu4lnz2hfcwa5qfn3zhsd0s23r22uqwzx9gu6cq5c4e76

TON: UQC4qlAOD9Nly4K_66GJ_yCsSM3x2sB0vZ2GrBQbc--gZUui

DOGE: DTjNYmbtymzcjUiV4MsZY8MP4dM7MJ6qLC

XMR: 44qRqM6YtnxXUhkgCFqDDrKMPjWriu69FLBoop8Kwp7e1VQsBUJoVQ8JYQjfMV5C6uidTUgSSyoJ65mq8aYG2esZ1rrqfwt