# qinglong: Task Scheduling for Python, JavaScript, Shell, and TypeScript > qinglong is a Docker-based task management platform that runs scripts written in Python3, JavaScript, Shell, or TypeScript on a cron schedule, managed through a built-in web panel. It suits developers who want to automate repetitive scripts without deploying a dedicated job queue. **whyour/qinglong** — 支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台（Timed task management platform supporting Python3, JavaScript, Shell, Typescript）. - Repository: https://github.com/whyour/qinglong - Website: https://qinglong.online - Stars: 19,907 · Forks: 3,221 - Language: TypeScript - License: Apache-2.0 - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/whyour-qinglong ## A Web Panel for Cron Scripts in Four Languages qinglong addresses a specific gap: running ad-hoc automation scripts on a schedule without setting up a full-featured job queue. Its primary audience is developers who maintain a collection of Python3, JavaScript, Shell, or TypeScript scripts and want to manage them, check their logs, and update environment variables from a browser. The platform ships as a self-contained Docker image. Once running, it presents a web panel at port 5700 where you create tasks, assign cron expressions, and browse per-run output logs. Scripts can be uploaded through the panel or pulled from a subscription source. Environment variables are editable in the panel and available to every script at runtime. For anyone with more than a handful of scripts, the online log viewer matters. Rather than accessing the container to inspect output, each run appends its stdout to a log file that the panel displays. The panel also supports dark mode and a mobile layout, which is useful when checking on a running task from a phone. The README lists system-level notifications, second-level cron granularity, and support for managing the panel via a remote CLI as additional features. ## Architecture: Node.js Backend and gRPC Bridge The panel's backend runs on Node.js, written in TypeScript and compiled together with the frontend. The primary HTTP port is 5700, controlled by the BACK_PORT variable in the .env file. A separate gRPC server listens on port 5500 (GRPC_PORT), used for agent communication and remote management. These two ports are the only network surface you need to expose. Task execution is delegated to the host system's scheduler inside the container. When using the alpine Docker image, that scheduler is Alpine's crond, which requires the container to run as root. The debian image uses a different cron implementation that supports non-root execution. If your host policy forbids root containers, the debian image is the correct choice. The panel stores its data, including scripts, logs, environment variables, and configuration, under the /ql/data volume mount. Keeping that directory backed up is sufficient to restore the panel after a container replacement. The repository also includes sample files under sample/ covering notify scripts (notify.js, notify.py) and a task template (task.sample.sh), which show the expected structure for scripts the scheduler can run. ## Installing qinglong with Docker The project publishes two Docker images: whyour/qinglong:latest, built on Alpine, and whyour/qinglong:debian, built on Debian Slim. Pull either with: ```bash docker pull whyour/qinglong:latest docker pull whyour/qinglong:debian ``` The debian image is required when you need to run as a non-root user, because Alpine's crond requires root. The following command mounts local storage and exposes the panel on port 5700: ```bash docker run -d \ -v /path/to/ql/data:/ql/data \ -p 5700:5700 \ --user qinglong \ --name qinglong \ whyour/qinglong:debian ``` After the container starts, open http://your-host:5700 and complete the first-time setup wizard. Before launch, configure JWT_SECRET and JWT_EXPIRES_IN in the .env file. LOG_LEVEL defaults to 'info'. The GRPC_PORT defaults to 5500 and BACK_PORT to 5700. For machines running Debian, Ubuntu, or Alpine natively, an npm package is also available: ```bash npm i @whyour/qinglong ``` This approach requires you to install Node, Python3, pip3, and pnpm separately. It is a lighter option for servers where Docker is unavailable. The package targets Debian, Ubuntu, and Alpine systems; the README notes that npm version 2.22.0 requires manual installation of those runtimes. ## Second-Level Scheduling and the Remote CLI One capability that separates qinglong from a plain cron wrapper is support for second-level task granularity. Standard Unix cron fires no finer than once per minute. qinglong accepts cron expressions with a seconds field, so tasks can run at sub-minute intervals. Remote management is handled by the separate npm package @whyour/qinglong-cli, which requires Node.js 22.12 or later. Install it globally and authenticate with your panel: ```bash npm install -g @whyour/qinglong-cli ql login --url https://ql.example.com ql auth status --json ql task list --json ql subscription list --json ql --help ``` After logging in with a Client ID and Secret (created under System Settings in the panel), the ql command exposes tasks, subscriptions, environment variables, scripts, and configuration as JSON output. This makes the CLI usable from shell scripts and from AI agent workflows. The QL_LANG=en environment variable switches the help text to English. The panel also ships with its own local ql command, which uses the same binary name. If you install the CLI package on a machine that already runs the panel, use a separate installation directory to avoid overwriting the built-in command. The remote CLI package also ships a skill definition for AI agents, covering authentication, command selection, and result checking. ## Where qinglong Falls Short qinglong is designed for a single-node deployment. There is no built-in clustering or horizontal scaling. If a script fails, the panel shows the log output, but the README does not document automatic retry configuration. Teams that need guaranteed delivery, retry-on-failure with back-off, or distributed execution across multiple machines should look at a purpose-built job queue: BullMQ for Node.js workloads or Celery for Python projects both address those requirements with features qinglong does not provide. The platform relies on the runtimes installed inside the Docker image. If a Python script depends on a library not included in the base image, you must add it manually, either by entering the container or through the panel's dependency interface. The alpine image cannot use packages that depend on glibc; switch to the debian image for those dependencies. The repository has no GitHub releases. Versioning is tracked through the npm package at version 2.22.0 and through Docker image tags. There is no CHANGELOG file listed among the top-level repository entries, which means tracking what changed between versions requires comparing image manifests or npm release notes. ## Maintenance and Licence The last push to the repository was on 2026-09-27. The package version is 2.22.0 and the packageManager field pins pnpm at 8.3.1. The project uses a development workflow with nodemon for the backend and a pnpm-based frontend build. The source code is licensed under the Apache License 2.0. This allows use in proprietary products without requiring you to publish modifications, unlike copyleft licences. You must preserve copyright notices and the LICENSE file when distributing the software. There is no official LTS policy described in the README. The 'latest' Docker tag tracks the alpine build and is updated without a versioned release. For production deployments, pinning to a specific image digest (rather than the 'latest' tag) prevents unexpected updates from breaking your environment between container restarts. ## Conclusion qinglong fits developers who run personal automation scripts on a single Docker host and want to manage them through a web interface rather than editing crontabs by hand. It is not suited for distributed workloads or jobs that require guaranteed delivery or automatic retry. Before deploying, verify that the Docker image includes every runtime your scripts depend on, and pin the image digest if you need reproducible deployments. ## FAQ ### Can qinglong run scripts written in more than one language? Yes. The platform executes Python3, JavaScript, Shell, and TypeScript scripts. Each script is run by its respective runtime, which must be present in the container image. ### How do I manage qinglong remotely from a terminal or pipeline? Install the @whyour/qinglong-cli npm package (Node.js 22.12 or later required), then authenticate with ql login --url https://your-host. The ql command can list tasks, subscriptions, and environment variables as JSON output, which suits both shell automation and AI agent workflows. ### What is the difference between the alpine and debian Docker images? The alpine image is the default and builds on Alpine Linux. The debian image uses Debian Slim and is required when running as a non-root user, because Alpine's crond requires root. Pass --user qinglong when starting the debian container. ## Sources - [Official documentation](https://qinglong.online) - [Official README](https://github.com/whyour/qinglong#readme) - [Project repository](https://github.com/whyour/qinglong) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/whyour-qinglong