js-udocker / udocker.js

News

• Added OnlyOffice compose example

2026/03/20

• Added support for copy from image
• Multi-stage supports target in compose

2026/03/13

• Added udocker compose [--dry] [--build-only]
  • now supports .env loading
  • I've successfully ran cal.com with some patches
    • Explanations in calcom_tutorial.md
• Added inspect -c

2026/03/11

• Added udocker compose [--force-recreate]
  • experimental for now, only supports simple files
• udocker run / compose by udocker_wrapper.sh
• Termux install/uninstall script
• multi-stage Dockerfile for udocker build

2026/03/05

• Added udocker build
• specifically for openclaw/Dockerfile

Introduction-中文

• 這個專案讓你能在沒有root權限的安卓手機
• 跑類似以下功能
  • docker run
  • docker build
  • docker compose
• .
• 這個 js-udocker 是基於python寫的那個原版
• udocker 1.3.17 的原始碼重寫的JavaScript版本。
• 但原版沒有build和compose的功能
  • 原版網址:
  • https://github.com/indigo-dc/udocker
• .
• 此專案的程式碼 大部分由 GPT Codex 產生。
• udocker_wrapper.sh lib/: build.mjs compose.mjs 主要是我寫的
• .
• 這邊有我的APP連結，可以在終端機直接使用udocker
  • https://drive.google.com/drive/folders/18iwbKrAZfA-HoTSP9I5MzGz5xVFMZ4bg
• 但也能在Termux安裝(較少測試)
  • sh termux_install.sh

使用方式

以下指令均以專案根目錄執行：

bun udocker.js pull ubuntu:latest
bun udocker.js pull --pull=always ubuntu:latest
bun udocker.js pull --pull=never ubuntu:latest
bun udocker.js pull --quiet ubuntu:latest
bun udocker.js create --name=myubuntu ubuntu:latest
bun udocker.js import rootfs.tar myimage:latest
bun udocker.js export -o rootfs.tar <container-id|name>
bun udocker.js save -o image.tar myimage:latest
bun udocker.js load -i image.tar
bun udocker.js inspect [-c|-p] myimage:latest
bun udocker.js verify myimage:latest
bun udocker.js manifest inspect myimage:latest
bun udocker.js ps [RegExp]
bun udocker.js rm <container-id|name> [name2] [name3]
bun udocker.js rmi <repo/image:tag>
bun udocker.js rename <old-name> <new-name>
bun udocker.js images
bun udocker.js help

bun udocker.js build -t <container_name> [-y | -i] [-f file] [--build-arg KEY=VAL] .

sh udocker_wrapper.sh run [--proot] [--bypass-registry] [-p port:port] [-v volume] [-w workdir] [--rm] [--name=<name>] [--entrypoint=<file>] [--isolated] <container/image name>

sh udocker_wrapper.sh compose [-f compose_file] [-y | -i] 
[--dry] [--build-only] [--repl] [--json] [--force-recreate]

sh udocker_wrapper.sh search <keyword>
sh udocker_wrapper.sh dir <shell_cmd>

run --bypass-registry 會略過 registry/pull，直接使用本地已有的 image metadata 與 layers；cache 不完整時建立會失敗。

指令說明

• pull [--pull=missing|always|never] [--platform=os/arch[/variant]] [--registry=URL] [--index=URL] [-q|--quiet] <repo/image:tag>：下載 image layers 與 metadata
• import <tar> <repo/image:tag>：匯入 tar（docker export）為 image
• import - <repo/image:tag>：從 stdin 匯入 tar（docker export）
• export -o <tar> <container>：匯出 container 檔案樹到檔案
• export - <container>：匯出 container 檔案樹到 stdout
• load -i <exported-image>：載入 docker save 檔案
• load：從 stdin 載入 docker save 檔案
• save -o <imagefile> <repo/image:tag>：輸出 docker save 檔案
• inspect [-p] <repo/image:tag|container>：顯示 metadata 或 container ROOT 路徑
• inspect -c <repo/image:tag|container>：顯示 metadata 的config部分
• verify <repo/image:tag>：驗證 image
• manifest inspect <repo/image:tag>：顯示 manifest
• create [--name=NAME] <repo/image:tag>：由 image 建立 container
• build -t <name> [-y | -i] <context>：從Dockerfile建立單層容器，-y是同意建立容器的所有過程，-i會每次詢問(預設值)
• compose [-f 檔名] [-y | -i]：一次建立許多容器並且跑起來，-y是同意建立容器的所有過程，-i會每次詢問(預設值)
• ps：列出 container
• rm <container-id|name>：刪除 container
• rmi <repo/image:tag>：刪除 image
• rename <old-name> <new-name>：變更 container 名稱

---

Introduction-English

• Run on non-rooted Android devices
• the docker-like functions below:
  • docker run
  • docker build
  • docker compose
• .
• This js-udocker is a JavaScript rewrite of the original python version udocker 1.3.17 (based on its code)
• but the original version lacks build/compose
  • Original version url:
  • https://github.com/indigo-dc/udocker
• .
• Most of the code in this project is generated by GPT Codex .
• udocker_wrapper.sh lib/: build.mjs compose.mjs is mainly written by me
• .
• Here is the link to my App, with direct access to udocker in the Terminal applet:
  • https://drive.google.com/drive/folders/18iwbKrAZfA-HoTSP9I5MzGz5xVFMZ4bg
• You can also install in Termux(less tested)
  • sh termux_install.sh

Usage

Run the following from the project root:

bun udocker.js pull ubuntu:latest
bun udocker.js pull --pull=always ubuntu:latest
bun udocker.js pull --pull=never ubuntu:latest
bun udocker.js pull --quiet ubuntu:latest
bun udocker.js create --name=myubuntu ubuntu:latest
bun udocker.js import rootfs.tar myimage:latest
bun udocker.js export -o rootfs.tar <container-id|name>
bun udocker.js save -o image.tar myimage:latest
bun udocker.js load -i image.tar
bun udocker.js inspect [-c|-p] myimage:latest
bun udocker.js verify myimage:latest
bun udocker.js manifest inspect myimage:latest
bun udocker.js ps [RegExp]
bun udocker.js rm <container-id|name> [name2] [name3]
bun udocker.js rmi <repo/image:tag>
bun udocker.js rename <old-name> <new-name>
bun udocker.js images
bun udocker.js help

bun udocker.js build -t <container_name> [-y | -i] [-f file] [--build-arg KEY=VAL] .

sh udocker_wrapper.sh run [--proot] [--bypass-registry] [-p port:port] [-v volume] [-w workdir] [--rm] [--name=<name>] [--entrypoint=<file>] [--isolated] <container/image name>

sh udocker_wrapper.sh compose [-f compose_file] [-y | -i]
[--dry] [--build-only] [--repl] [--json] [--force-recreate]

sh udocker_wrapper.sh search <keyword>
sh udocker_wrapper.sh dir <shell_cmd>

run --bypass-registry skips registry/pull access and uses existing local image metadata and layers; creation fails if the cache is incomplete.

Commands

• pull [--pull=missing|always|never] [--platform=os/arch[/variant]] [--registry=URL] [--index=URL] [-q|--quiet] <repo/image:tag>: download image layers and metadata
• import <tar> <repo/image:tag>: import tar (docker export) to image
• import - <repo/image:tag>: import tar from stdin (docker export)
• export -o <tar> <container>: export container directory tree to file
• export - <container>: export container directory tree to stdout
• load -i <exported-image>: load image from file (docker save)
• load: load image from stdin (docker save)
• save -o <imagefile> <repo/image:tag>: save image with layers to file
• inspect [-p] <repo/image:tag|container>: print metadata or container ROOT path
• inspect [-c] <repo/image:tag|container>: print metadata's config part
• verify <repo/image:tag>: verify image
• manifest inspect <repo/image:tag>: print manifest metadata
• create [--name=NAME] <repo/image:tag>: create a container from an image
• build -t <name> [-y | -i] <context>: create single-layered container from Dockerfile, -y will agree with all the building process while -i prompts every time interactively(default)
• compose [-f file] [-y | -i]: Create several containers at a time and run them, -y will agree with all the building process while -i prompts every time interactively(default)
• ps: list containers
• rm <container-id|name>: delete a container
• rmi <repo/image:tag>: delete an image
• rename <old-name> <new-name>: rename a container alias