Skip to content

adb-modules-guide.md

Latest commit

 

History

History
156 lines (109 loc) · 3.27 KB

adb-modules-guide.md

File metadata and controls

156 lines (109 loc) · 3.27 KB
Raw

ADB Modules Guide

This guide is for module authors and testers. For the exact API contract, see ADB Modules API reference.

What This System Is

ADB Modules are ZIP packages installed into Nightzuku private storage and executed through the active Nightzuku server.

  • ADB-started Nightzuku: scripts run with ADB shell privileges.
  • Root-started Nightzuku: scripts run with root privileges.
  • Safe mode: manual actions only.
  • Full access: allows stronger module behavior.
  • Background actions: required before service.sh can run.

This is a real module runner, not a visual stub. It installs ZIPs, parses metadata, stores module files, runs shell scripts through Nightzuku, opens local WebUI, tracks enabled state, deletes modules, and writes last-run logs.

It is not a Magisk/KSU systemless overlay implementation. There are no mount hooks, no /data/adb/modules compatibility promise, and no long-running daemon supervisor yet.

Minimal Module

Create this structure:

my-module/
├── module.prop
├── action.sh
└── webui/
    └── index.html

module.prop:

id=my-module
name=My Module
version=1.0
versionCode=1
author=Author
description=Short module description

action.sh:

#!/system/bin/sh
echo "module=$SHIZUKU_MODULE_ID"
echo "mode=$SHIZUKU_MODULE_MODE"
id

Package it:

cd my-module
zip -r ../my-module.zip .

Install my-module.zip from the ADB Modules screen.

Optional Files

Banner:

banner.png

WebUI:

webui/index.html

Background/service hook:

service.sh

Custom paths can be declared in module.prop:

banner=assets/banner.webp
webui=webui
usesShellBridge=true
action=scripts/action.sh

usesShellBridge=true is mandatory for WebUI pages that need window.Shizuku.

Script Environment

Scripts run from the module directory. Use these variables:

MODDIR=/data/user/0/kerneldroid.nightzuku/files/adb_modules/<id>
ASH_STANDALONE=1
SHIZUKU_MODULE_ID=<id>
SHIZUKU_MODULE_MODE=safe|custom|full
SHIZUKU_MODULE_TRUSTED=0|1
SHIZUKU_MODULE_BACKGROUND=0|1

Do not hardcode Magisk/KSU paths. Use $MODDIR.

Action vs Service

Use action.sh for user-triggered commands.

Use service.sh for background setup. It runs when:

  • The module is enabled.
  • Access mode is Full, or Custom with Service enabled.
  • Background actions are enabled in Settings.
  • Nightzuku binder is available.

The manager auto-runs enabled services once per binder session.

Full Trust

Full Trust is a per-module override. Long-press a module card to toggle. Trusted modules bypass global policy gates while respecting core safety limits (timeouts, output caps).

Safety Limits

  • ZIP path traversal is rejected.
  • Max entries: 2048.
  • Max extracted size: 200 MB.
  • Script timeout: 120 seconds.
  • Output retained: last 64 KB per stdout/stderr stream.

Timeout exit code is 124.

Logs

Logs are written inside the installed module directory:

logs/action-last.log
logs/service-last.log

Each log includes module id, script name, exit code, access mode, stdout, and stderr.

Test Module

The repository includes:

test-modules/adb-test-module.zip

Use it to verify install, enable/disable, Action, Service, WebUI, and banner rendering.