agentsclimarketplace

Test app

Skill JosephJoshua/starry-harness/skills/test-app

This skill should be used when the user asks to "run Nginx on StarryOS", "test application compatibility", "run Python on StarryOS", "test Linux app", "port application", "check app support", "run Rust compiler", "test Wayland", "run PostgreSQL", "run Redis", or wants to test and enable real mainstream Linux applications running on StarryOS.From its SKILL.md

Install
npx -y skills add JosephJoshua/starry-harness --skill test-app

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

10.8 KB, as published. Nobody here has run it

Test Real Linux Applications on StarryOS

Systematic workflow for selecting, building, testing, and enabling real mainstream Linux applications on StarryOS. The goal is to run ambitious, mainstream applications — not just toy programs. Each application exercises a different slice of the syscall surface, so testing them exposes gaps and validates breadth.

Workflow Overview

Seven-phase cycle: Select → Audit → Gap Analysis → Build → Inject & Run → Fix Blockers → Verify & Report. Each phase produces concrete artifacts. There is no fixed ordering — pick whatever application is most interesting or valuable and go for it.

Phase 1: Select Application

Choose a target application based on interest, competition value, and what syscall areas need testing.

Application catalog (not a rigid ordering — pick any):

ApplicationDemonstratesSyscall Focus
BusyBoxCore POSIX process modelfork, exec, pipe, signals
NginxNetwork server, event loopsockets, epoll, sendfile, mmap
RedisIn-memory DB, persistencesockets, epoll, fork, fsync
PostgreSQLFull RDBMS, IPC, shared memoryshmget/shmat, semaphores, mmap, socket
Python (CPython)Complex runtime, threadingmmap, futex, clone, signals, pipes
Rust CompilerFull toolchainclone3, getrandom, flock, execve
SQLiteEmbedded DBflock, mmap, fsync, fcntl
curl / wgetHTTP clientsocket, connect, DNS, TLS
LuaLightweight scriptingMinimal: mmap, read/write, signals
SyzkallerKernel fuzzerEverything — designed to exercise all syscalls

Interactive selection: Present this table to the user and ask which application to target. The user may also specify any other Linux program not on this list — in that case, proceed to Phase 2 (Syscall Audit) to discover the requirements from scratch using strace in Docker.

Selection criteria (when the user wants a recommendation):

  • Check os/StarryOS/tests/known.json to see which syscalls are already working
  • More unique/ambitious applications (PostgreSQL, rustc) are more impressive than common ones
  • Each app should demonstrate a distinct capability (networking, threading, filesystem, IPC)
  • Consult references/app-requirements.md for full syscall requirements per application
  • If the user picks a custom app not in the catalog, skip to Phase 2 — strace it first

Record the decision: Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/journal-entry.sh APP "Selected <app> as next target" "<rationale>"

Phase 2: Syscall Audit

Capture the complete syscall profile of the target application by running it under strace inside a Docker Linux container.

Run the strace capture:

docker run --rm -v $(pwd):/work ubuntu:24.04 sh -c '
  apt-get update && apt-get install -y strace <app-package> &&
  strace -f -o /work/strace-<app>.log <app-command> &&
  # Extract unique syscall names
  awk -F"(" "{print \$1}" /work/strace-<app>.log | sort -u > /work/syscalls-<app>.txt
'

For applications that require building from source, use the cross-compilation instructions in references/app-requirements.md to build a native x86 binary first, then strace it.

Alternatively, for simple captures, use the existing linux-ref-test script:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/linux-ref-test.sh <test-wrapper.c> /tmp/app-baseline.txt

Output: A syscalls-<app>.txt file listing every unique syscall the application invokes during normal operation, including startup and shutdown.

Phase 3: Gap Analysis

Compare the application's syscall requirements against StarryOS's implemented syscalls.

Step 1 — Load the syscall dispatch table: Read os/StarryOS/kernel/src/syscall/mod.rs and extract every syscall number handled. This file contains the master match dispatch.

Step 2 — Cross-reference with known.json: Read os/StarryOS/tests/known.json for each required syscall. Classify each as:

  • Implemented and tested — Exists in dispatch table and passes tests
  • Implemented but untested — Exists in dispatch but no test or known bugs
  • Stub — Handler exists but returns Ok(0) or ENOSYS without real logic
  • Missing — No handler in the dispatch table at all

Step 3 — Produce the gap matrix: Create a table:

SyscallRequired ByStarryOS StatusBlocking?Notes
epoll_create1NginxImplementedNoPasses test
sendfileNginxStubYesReturns Ok(0), no data transfer
accept4NginxMissingYesNot in dispatch

Step 4 — Estimate fix effort: For each blocking syscall, scan the handler code (if it exists) and estimate:

  • Quick fix (< 1 hour): wrong errno, missing flag, off-by-one
  • Medium fix (1-4 hours): partial implementation needs completing
  • Hard fix (> 4 hours): entirely new subsystem or complex interaction

Phase 4: Build for StarryOS

Cross-compile the application as a static riscv64 binary using musl.

General approach:

# Install cross toolchain
apt-get install -y gcc-riscv64-linux-gnu
# Or use musl cross-compiler for fully static binaries
# See references/app-requirements.md for per-app build instructions

Requirements:

  • All binaries MUST be statically linked — StarryOS does not support dynamic linking for external apps
  • Target architecture: riscv64gc (riscv64-linux-musl for musl toolchain)
  • Optimize for size when possible (-Os) to keep the rootfs small
  • Strip debug symbols for the final binary (riscv64-linux-musl-strip)

Per-application build instructions are in references/app-requirements.md. Follow them exactly — each application has specific configure flags and patches needed.

Output: A static riscv64 ELF binary (or set of binaries) ready for injection into the StarryOS rootfs.

Phase 5: Inject and Run

Use the StarryOS rootfs injection pipeline to place the binary and test it on QEMU.

Step 1 — Inject into rootfs:

cd os/StarryOS
# Copy binary into the rootfs tree
cp /path/to/app-binary tests/bin/<app>
# Or use the pipeline injection step
bash ${CLAUDE_PLUGIN_ROOT}/scripts/pipeline.sh <app>

Step 2 — Create a test wrapper: Write a minimal shell script or C wrapper that launches the application and captures output:

#!/bin/sh
# /test/run-<app>.sh
/bin/<app> <args>
echo "EXIT_CODE=$?"

Step 3 — Boot and run:

cd os/StarryOS
bash ${CLAUDE_PLUGIN_ROOT}/scripts/pipeline.sh <app>

Step 4 — Capture output: The pipeline writes output to os/StarryOS/tests/results/test_<app>.txt. Inspect for:

  • Kernel panics or traps
  • ENOSYS errors (unimplemented syscalls)
  • Incorrect behavior vs. Linux baseline
  • Successful completion with correct output

Phase 6: Fix Blockers

For each failing syscall or crash, dispatch the hunt-bugs skill to fix it.

Triage blockers by impact:

  1. Kernel panics — fix first, they prevent any further testing
  2. ENOSYS returns — implement the missing syscall handler
  3. Wrong behavior — fix the semantic bug in the existing handler
  4. Performance issues — defer unless they cause timeouts

For each blocker:

  1. Identify the syscall from the error output or strace log
  2. Locate the handler in os/StarryOS/kernel/src/syscall/
  3. Use the hunt-bugs skill workflow: generate a targeted test, compare with Linux, fix, verify
  4. Dispatch the kernel-reviewer agent for code quality review
  5. Re-run the application after each fix to check progress

Track progress: Update os/StarryOS/tests/known.json as syscalls are fixed. Update the gap matrix from Phase 3 to reflect current status.

Iterate: After fixing one blocker, re-run the application. It will likely hit the next missing syscall. Repeat until the application either runs successfully or hits an infeasible blocker.

Phase 7: Verify End-to-End and Report

Confirm the application runs correctly and generate the competition report.

Verification checklist:

  • Application starts without kernel panics
  • Application produces correct output matching the Linux baseline
  • Application handles basic error cases (invalid input, network timeout, etc.)
  • Application shuts down cleanly
  • No regressions in existing syscall tests: cd os/StarryOS && cargo xtask test arceos
  • Kernel passes clippy: cargo xtask clippy --package starry-kernel

Dispatch the linux-comparator agent to run the application on both Docker Linux and StarryOS, capturing output for side-by-side comparison.

Generate the compatibility report: Write to docs/starry-reports/apps/APP-NNN-<name>.md using this structure:

# APP-NNN: <Application Name>

## Summary
- Application: <name and version>
- Status: PASS / PARTIAL / FAIL
- Date: <YYYY-MM-DD>
- Syscalls exercised: <count>
- Syscalls fixed during porting: <list>

## Build
- Toolchain: <compiler and flags>
- Binary size: <size>
- Build notes: <any patches or workarounds>

## Test Results
- Linux baseline: <summary>
- StarryOS: <summary>
- Divergences: <list>

## Syscall Coverage
| Syscall | Status | Notes |
|---------|--------|-------|

## Remaining Issues
- <issue 1>
- <issue 2>

Journal entry: bash ${CLAUDE_PLUGIN_ROOT}/scripts/journal-entry.sh APP "<app> testing complete — <status>" "<summary>"

Key File Locations

ResourcePath
Syscall dispatchos/StarryOS/kernel/src/syscall/mod.rs
Syscall handlersos/StarryOS/kernel/src/syscall/
Known syscall registryos/StarryOS/tests/known.json
Test binariesos/StarryOS/tests/bin/
Test resultsos/StarryOS/tests/results/
Pipeline script${CLAUDE_PLUGIN_ROOT}/scripts/pipeline.sh
App compatibility reportsdocs/starry-reports/apps/
Work journaldocs/starry-reports/journal.md

Key Scripts

ScriptPurpose
${CLAUDE_PLUGIN_ROOT}/scripts/linux-ref-test.shRun test in Docker Linux for baseline behavior
${CLAUDE_PLUGIN_ROOT}/scripts/journal-entry.shAppend structured entry to the work journal
${CLAUDE_PLUGIN_ROOT}/scripts/man-lookup.shFetch man page for a syscall

Agents

  • linux-comparator — Run application on Docker Linux and StarryOS side-by-side, produce structured comparison
  • kernel-reviewer — Review kernel code changes for Rust idioms, safety, and correctness

Additional Resources

Reference Files

  • references/app-requirements.md — Per-application syscall requirements, build instructions, strace templates, and feasibility analysis

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.