iStoreOS Feature Overview

Based on 13 operations skills for the iStoreOS/OpenWrt environment

1. System Overview

iStoreOS is an OpenWrt-based soft router / home server system:

• Package management: is-opkg / opkg (never use apt/yum/dnf/systemctl)
• App system: iStore app store (app-meta-*) + traditional opkg packages + Docker apps (istorec)
• Config management: UCI unified config (/etc/config/*) + uci CLI
• Service management: /etc/init.d/* SysV scripts + procd
• Web UI: LuCI (uhttpd + rpcd)
• Partitions: read-only ROM (/rom baseline) + writable overlay (/overlay/upper)

Key Directories

Path	Purpose
/etc/config/	UCI config files
/etc/init.d/	Service start/stop scripts
/usr/lib/opkg/meta/*.json	iStore app metadata
/usr/libexec/istorec/<name>.sh	Docker app scripts
/usr/libexec/istore/overlay-backup	Full system backup tool
/overlay/upper	Writable layer (backup target)

2. App Search & Software Management

2.1 App search

• Local device metadata first (/usr/lib/opkg/meta/*.json)
• Fallback to the distributed apps.jsonl
• Top-3 candidates with name / title / type_hint / entry / why / score
• User confirmation required before installation

2.2 Installation routing

Type	Detection	Command
iStore meta app	/usr/lib/opkg/meta/<name>.json exists	is-opkg install app-meta-<name>
Docker iStore app	meta depends includes docker-deps	istorec container install
Traditional opkg	otherwise	opkg list / info / install

Supports install / upgrade / remove and autoconf automatic configuration (AUTOCONF=<name> path=<base> enable=<0|1>).

2.3 Post-install verification

• meta/opkg: opkg status <pkg> or opkg list-installed | grep <pkg>
• Services: /etc/init.d/<svc> status
• Docker apps: docker ps --all -f 'name=^/<name>$'

3. Docker Capabilities

3.1 Docker availability loop

1. Check install: command -v docker; command -v dockerd
2. Check service: /etc/init.d/dockerd status
3. Install/repair via iStoreOS path (iStore meta first)
4. Enable auto-start and restart
5. Verify: docker version + docker info + docker ps

3.2 Space check before install

• Check DockerRootDir free space (< 2 GiB needs handling)
• Check whether data_root is on the system disk (needs migration)

3.3 Safe data_root migration

• Only after explicit user confirmation; back up /etc/config/dockerd first
• Flow: stop dockerd → migrate → update UCI → restart → verify → rollback possible
• Verify with docker info and df
• Full system backup strongly recommended before migration

4. Network Acceleration (iStoreEnhance / KSpeeder)

4.1 Docker image acceleration

1. Ensure Docker is available
2. Auto disk selection + autoconf
3. Check install: opkg status app-meta-istoreenhance ...
4. Install: is-opkg install app-meta-istoreenhance
5. Check config: uci -q show istoreenhance — enabled=1 and non-empty cache
6. Enable and restart the service
7. Verify mirror linkage in dockerd config
8. Degradation: direct docker pull when acceleration unavailable

4.2 KSpeeder DomainFold download acceleration

• Host-based routing on one TLS port for registry mirror, GHCR and DomainFold handlers
• Maps origin URLs (e.g., github.com) to entry domains with a remap API
• Supports GitHub, GitLab, HuggingFace, common package repos and AI API domains
• Recommended unified ksget entry with retry + fallback chain

5. Service Management

The standard loop for "installed but not working":

Step	Action
1. Confirm script exists	ls -la /etc/init.d/<service>
2. Enable in init.d	enable && restart
3. Check UCI enable flag	uci -q show <config>, look for enabled=1 etc.
4. Verify	status + logread | grep -iE '<svc>|error|fail'

Key lessons: open the init script to verify enable flags instead of guessing; remind backup before destructive operations.

6. Storage & Disk Selection

base path is used by is-opkg AUTOCONF=<app> path=<base> to derive:

<base>/
├── Configs/    (ISTORE_CONF_DIR)
├── Caches/     (ISTORE_CACHE_DIR)
├── Public/     (ISTORE_PUBLIC_DIR)
│   └── Downloads/ (ISTORE_DL_DIR)

Selection priority: user-specified mount → external/data disk (/mnt/<name>) → system disk (with risk warning). Verify writability before use.

7. Backup & Restore

Type	Command	Target	Notes
Full system backup (recommended)	overlay-backup backup <DIR>	/overlay/upper	No network needed for restore, auto-reboot after
App list backup (optional)	backup	app-meta-* list + deps	Fast app list restore

• <DIR> must be on external storage
• Restore is a dangerous operation (auto-reboot), requires explicit confirmation

8. Fault Diagnosis

Principle: collect evidence first, conclude later; layer first, drill down later.

Quick routing:

• Install failure → confirm iStore meta vs opkg first
• docker pull failure → confirm daemon, then check registry_mirrors, switch to acceleration loop
• Disk full → locate mount point, then clean/migrate

9. LuCI Web UI Recovery

Principles: evidence first → soft recovery first (clear cache + restart rpcd/uhttpd) → avoid source edits → confirm before writes.

Recovery ladder:

1. Read-only diagnosis
2. Soft recovery (needs confirmation)
3. Locate broken file's owning package (read-only)
4. Generate fix candidates (read-only)
5. Reinstall core packages (confirmation + backup first)

10. Source-level Evidence Collection

• Read-only: no config writes, no UCI changes, no service restarts
• Default redaction for password/token/secret/key fields
• One-command collection of UCI summaries, init script snippets and LuCI file lists

11. .run Executable Handling

Flow: fetch → inspect → backup → confirm → execute → keep evidence.

• Treated as dangerous; backup confirmation required
• Read-only inspection first, never chmod +x blindly
• Reversible via is-opkg dotrun / is-opkg unrun

12. Security Principles

Principle	Description
Evidence before conclusion	Read-only diagnosis first, no guessing
Backup before danger	Mandatory backup reminder before writes
Explicit confirmation	CONFIRM_*=YES or user reply required
Scripts first	Prefer skill scripts over manual commands
Closed-loop verification	Verify after every operation
Read-only first	Diagnostics and evidence collection stay read-only
Default redaction	Mask keys/passwords/tokens in output

13. Typical Workflows

A: Install an app

verbal description → app-search (Top3) → user confirms name
  → package-manager (routed install)
  → service-manager (ensure enabled)
  → verification loop

B: Docker pull failure

docker-basics → docker-acceleration → if still failing → logs-and-diagnostics

C: Before installing Docker apps

space check → migrate data_root if needed (confirm + backup) → ensure acceleration ready

D: Install to a specific disk

storage-path (select disk, output base path) → AUTOCONF=<app> path=<base> enable=1

E: LuCI not opening

read-only diagnosis → soft recovery → locate problem file → reinstall (confirm + backup)