# Local Runtime Onboarding Design

Date: 2026-07-17

## Goal

Let a student who receives the AIPROS Lite source package start it locally, connect an installed local AI CLI with minimal setup, select it as the active runtime, and use it for Skill creation, evaluation, and execution. Conversation panels must expose every generated artifact and allow downloading individual files or the complete session as a ZIP.

## Scope

This first release targets only the local Node.js deployment started with `npm run local`. It does not add a cloud-to-desktop tunnel or a second resident bridge daemon. The existing local Node backend is the bridge between the browser and local CLI processes.

Included:

- Guided setup for Codex, Qoder CLI, CodeBuddy Code, Trae Agent, and a custom CLI.
- A copyable project command for setup and discovery.
- Runtime detection, authentication guidance, a real prompt test, and activation.
- Accurate non-interactive command presets for supported CLIs.
- Recursive artifact discovery, individual download/preview, and complete-session ZIP download.
- Advanced command, arguments, environment, and working-directory fields retained behind a disclosure.

Excluded:

- Cloudflare Worker execution of local commands.
- Automatic browser-triggered global package installation.
- A vendor SDK integration or a new local daemon.
- Rich in-browser rendering for every binary format; unsupported previews remain downloads.

## Approaches Considered

### A. Use the existing local Node backend as the bridge — selected

The browser calls the local AIPROS API, which discovers and spawns the selected CLI in the session working directory. This reuses the existing `local-cli` protocol and keeps the student workflow to one application process.

### B. Add a separate resident bridge daemon

This would help a cloud-hosted page reach a desktop runtime, but it adds installation, port, lifecycle, authentication, and troubleshooting overhead that is unnecessary for the local-only requirement.

### C. Integrate each vendor SDK or remote API

This could expose richer provider-specific events but would not reuse the student's installed CLI and would multiply credential and maintenance paths.

## Student Experience

The Runtime Registry becomes a guided four-step experience:

1. **Install**: choose a runtime and copy `npm run runtime:setup -- <runtime>`.
2. **Sign in**: follow a provider-specific one-line login instruction when needed.
3. **Test**: AIPROS first detects the executable and version, then runs a small non-interactive prompt in an isolated session directory.
4. **Select**: a successful test enables the “use this runtime” action and applies it to create, evaluate, and run by default.

The UI displays explicit states: not installed, installed/sign-in required, test passed, and current runtime. Normal users see only the guided controls. Advanced fields stay available in a collapsed section.

## Runtime Catalog and Discovery

A small runtime catalog provides stable metadata independent of database rows:

- runtime code and display name;
- executable candidates;
- macOS/Linux and Windows install commands;
- version arguments;
- login guidance;
- non-interactive execution argument template;
- supported purposes.

The setup command and API use the same catalog. Discovery checks `PATH` and known user-level binary locations without executing a shell command assembled from user input. A custom CLI keeps the current explicit command and argument fields.

Initial presets:

- Codex: `codex exec ... -C {workdir} -`, prompt through stdin.
- Qoder CLI: `qodercli -p {prompt} --yolo`.
- CodeBuddy Code: `codebuddy -p {prompt} --output-format text --dangerously-skip-permissions`.
- Trae Agent: `trae-cli run {prompt}` with provider configuration guidance.

Existing legacy runtime rows remain readable. A migration adds or corrects the new presets without deleting user configuration.

## Backend Flow

Runtime APIs expose catalog metadata and connection state alongside existing runtime data. Test has two stages:

1. Resolve the executable and run the version check with a short timeout.
2. Run a fixed harmless prompt in a temporary session directory using the actual adapter.

Only a successful real prompt test marks a runtime connected. Activation still persists through the runtime registry. Skill jobs resolve the selected runtime as today, construct the shared AIPROS prompt, spawn the CLI without a shell, and use the session directory as its workspace.

Errors are mapped to actionable states: command not found, login/configuration required, permission denied, timeout, unsupported platform, and non-zero CLI exit. Error responses must not expose environment secrets.

## Artifact Contract

The session directory is the source of truth for local CLI artifacts. At job completion the backend recursively lists user-visible files, excluding internal event/state files. The `files` stream event carries normalized relative paths.

The output download route accepts a safe relative path, including nested directories, and enforces containment within the session directory. MIME type and `Content-Disposition` are derived from the file. Conversation panels render a shared artifact card with:

- file name, type, and relative path;
- preview when browser-safe;
- direct download for every file;
- “download all as ZIP” for the session.

The ZIP endpoint recursively packages the same user-visible files and excludes internal state. This behavior is shared by create, evaluate, and sandbox/run conversations.

## Security

- Browser UI never launches an installer directly.
- Runtime processes use `spawn` with `shell: false`.
- Custom executable and argument values are stored as data, not concatenated shell scripts.
- All artifact paths are normalized and containment-checked.
- Environment variables are never returned in test errors or status payloads.
- Destructive/bypass permission flags are visible in advanced settings and documented as local-only behavior.

## Testing

- Unit-test runtime catalog metadata, OS-specific setup command selection, and executable discovery.
- Unit-test adapter argument rendering and prompt delivery.
- Route-test detect, real-test failure mapping, and activation gating.
- Route-test nested artifact download traversal protection and ZIP exclusion of internal files.
- Component/service-test runtime onboarding state derivation and artifact URL construction.
- Run all frontend service tests, relevant backend runtime/route tests, production build, and a local smoke test with an available CLI.

## Success Criteria

A new student can run `npm run local`, open Runtime Registry, copy one setup command, sign in, click test, select the runtime, and immediately use it in Skill creation, evaluation, or execution. Any files produced in nested or top-level session paths are visible in the conversation, individually downloadable, and available together as a ZIP.
