App desktop

devkit có hai app desktop: devkit.app, app menu bar cho macOS 14 trở lên, và devkit-gtk, app tray GTK 4 cho Linux. Hai app trông và hoạt động giống nhau. Cả hai chỉ là giao diện của CLI: mỗi nút chạy một lệnh devkit … --json, và một devkit watch --json giữ cho cửa sổ luôn cập nhật. Việc bạn làm trong terminal sẽ hiện lên app trong vài giây, và ngược lại.

Trên macOS, devkit là một biểu tượng trên menu bar (hình chiếc hộp, tô đầy khi có site đang chạy) và không có biểu tượng trên Dock. Bấm vào sẽ mở một panel:

Đầu panel: "devkit", một dòng tóm tắt như 3 site đang chạy, và nút mở cửa sổ quản lý.
Mỗi stack một thẻ: tên stack, 4/5 đang chạy, và mỗi service một chấm (rê chuột để xem trạng thái và vai trò).
Đang chạy: mọi site và lane đang chạy kèm URL (bấm để mở) và nút dừng; tiếp theo là một link như 2 site đã dừng → dẫn tới cửa sổ quản lý.
Chạy tất cả (lần lượt từng site và lane đang dừng, không bị ẩn) và Dừng tất cả (lane trước, rồi tới site).
AI agent đang kết nối, khi có agent chạy devkit mcp, kèm thời điểm lần gọi gần nhất. Mục này mở phần MCP.
Mở devkit…, Chạy doctor (báo cáo đầy đủ), Thoát devkit.

Trên Linux, nội dung này là một menu tray (StatusNotifierItem). Mỗi stack là một menu con chứa các service của nó; mỗi site đang chạy là một menu con có Mở, Sao chép URL và Dừng. Bấm chuột trái vào biểu tượng sẽ mở cửa sổ quản lý. KDE Plasma, Xfce, Cinnamon, MATE, LXQt và Budgie có hiện tray; GNOME cần extension AppIndicator. Khi không có tray, hoặc khi chạy với --no-tray, app hiện panel thành một cửa sổ nhỏ và thoát khi cửa sổ cuối cùng đóng lại.

Cửa sổ quản lý

Thanh bên có bảy mục, theo thứ tự: Sites, Lanes, Stacks, PHP, Templates, Cài đặt, MCP.

Tìm kiếm (Tìm site) có ở Sites và Lanes, khớp theo tên, branch hoặc URL, không phân biệt hoa thường và dấu.
Thanh trạng thái ở dưới cùng cho biết có bao nhiêu site và bao nhiêu site đang chạy, Engine mặc định: artisan · port 8100–8999, và bên phải là các MCP agent đang kết nối (link tới mục MCP).
Thông báo: kết quả của một thao tác (output của một thao tác nhanh, một lỗi kèm gợi ý của devkit) hiện thành banner ở đầu mục, đóng bằng Đóng.
Mỗi site một thay đổi tại một thời điểm: khi devkit đang làm việc với một site (đang khởi động, checkout, clone, khôi phục), dòng của site đó hiện vòng xoay và các mục có thể làm thay đổi site sẽ phải chờ. Các mục mở, xem và log vẫn dùng được.

Sites

Trên cùng là một dải cho mỗi stack với các chấm service, và Hộp thư ↗ khi stack có mail catcher. Tiếp theo là các site: Đã park (mỗi thư mục park một nhóm, bên phải có Clone từ git…) và Đã liên kết. Phần đầu có Liên kết thư mục… và Park thư mục…, cả hai đều mở hộp chọn thư mục.

Cột	Nội dung
Site	tên site (bấm để xem chi tiết site); lane thụt vào dưới site của nó với lane 1, lane 2…
Branch	branch git, chấm cam khi có thay đổi chưa commit, và bên dưới là số commit trước/sau hoặc chưa có upstream
Engine	artisan hoặc caddy
PHP	hộp chọn phiên bản của site (lane hiện phiên bản của site, kế thừa)
URL	địa chỉ site được phục vụ
Database	tên database
Doctor	OK, 2 cảnh báo hoặc 1 lỗi từ `devkit doctor <site>`, chạy khi mở app và khi có site mới xuất hiện
Thao tác	chạy hoặc dừng, mở trong trình duyệt, thùng rác đỏ (xoá; với lane: gỡ) và `…`

Menu `…`

Nút …, hoặc chuột phải vào dòng, mở menu của site: một panel có tên site và những gì nó đang chạy, tiếp theo là các nhóm sau.

Nhóm	Site	Lane
Mở	Mở trong trình duyệt `⌘O`, Mở trong editor `⌘E`, Mở terminal tại đây `⌘T`, Sao chép URL `⌘C`	giống site
Tool	Lane mới…, Sửa template .env…, Xem log, Modules, Chạy doctor	Xem log, Modules, Chạy doctor
Thao tác nhanh	Clear log, Clear cache, Publish core assets và các thao tác riêng của site, mỗi mục kèm lệnh tương ứng làm gợi ý	giống site
Web	Đổi engine…, Xdebug…	Xdebug…
Database	Tạo snapshot database, Khôi phục snapshot…	Tạo snapshot database, Đặt lại database từ <site>…
Xoá	Ẩn khỏi devkit (giữ file), Xoá site… (xoá code)	Xoá lane… (xoá database của lane)

Phím tắt dùng được khi panel đang mở (trên Linux là Ctrl+O/E/T/C). Trên macOS, menu chuột phải có đủ các mục này nhưng không có phím tắt; trên Linux, chuột phải mở chính panel đó.

Chi tiết site

Bấm vào tên một site. Trên cùng là breadcrumb, trạng thái, URL và thanh branch: hộp chọn branch (branch local, branch remote chưa có bản local, Branch mới…), trạng thái đồng bộ (đã khớp với origin/main · sạch), Fetch, Pull (thành Pull ↓3 màu xanh khi đang sau), Push (thành Push ↑2 màu xanh khi đang trước) và Gồm cả submodule (bật sẵn). Chọn một branch không checkout ngay: một hộp sẽ nói điều gì sẽ xảy ra (site chạy lại, submodule chuyển theo hay giữ nguyên) và chờ bạn bấm Checkout.

Bên dưới: các thao tác nhanh gom thành một nhóm nút, Mở trong editor, Lane mới… (với lane: Xoá lane…) và Chạy site / Dừng site. Tiếp theo là các thẻ Engine (kèm port), PHP (hộp chọn; lane hiện 8.3 · theo core-development), Database, Xdebug (mở sheet Xdebug) và Hộp thư khi stack có mail catcher.

Đổi PHP từ thẻ này sẽ hiện một banner: Đang chuyển sang PHP 8.2, rồi Đã chuyển sang PHP 8.2, cho biết serve và các process PHP vẫn dùng phiên bản cũ cho tới khi site chạy lại, lane đi theo site, và mọi vấn đề doctor phát hiện với phiên bản mới. Chạy lại ngay chạy lại site và các lane đang chạy của nó; Hoàn tác trả lại phiên bản cũ. (Hộp chọn trong bảng Sites và trong tab Cài đặt đổi phiên bản mà không hiện banner.)

Tiếp theo là năm tab:

Processes: Dòng serve (php artisan serve --port=8100, hoặc caddy route → php-fpm) kèm pid, Chạy lại, Dừng / Chạy và Log; tiếp theo là từng process với lệnh và port, trạng thái (đang chạy, đã dừng, đã thoát kèm những dòng cuối khi rê chuột), công tắc Tự chạy (cùng site), chạy, dừng, chạy lại và Log. Log đang chọn hiện ở bên dưới, làm mới mỗi hai giây, kèm Mở trong log….
Modules và Extensions: Các submodule trong modules/ và extensions/. Hàng trên cùng: ô Branch, Tạo nếu chưa có, Checkout trong mọi modules, Fetch, Pull tất cả, Push tất cả (bật khi có module đang trước) và, ở Extensions, Thêm extension…. Mỗi dòng: hộp chọn branch (branch của module, branch mà .gitmodules theo dõi, branch của site, Branch mới…), chấm xanh khi module không ở branch được theo dõi, Theo dõi, Thay đổi (sạch hoặc 3 thay đổi), Trước / sau, Pull, Push và Terminal. Dòng có thay đổi chưa commit sẽ từ chối checkout: Hãy commit hoặc stash trước.
Database: Database (với lane là fork từ core_development), Tạo snapshot database…, với lane có Đặt lại từ <site>…, và danh sách snapshot (tên, ngày tạo, dung lượng) kèm Khôi phục… và Xoá….
Cài đặt: Engine (Đổi engine…), PHP, Xdebug (Xdebug…), Database, thư mục kèm Hiện trong Finder, và branch.

Các sheet

Mọi thay đổi cần bạn quyết định đều mở một sheet. Return bấm nút chính và Esc huỷ, trừ khi devkit đang làm việc. Nút đỏ, nút có tính phá huỷ, không có phím tắt Return.

Sheet	Những gì sheet hỏi	Mặc định
Lane mới từ <site>	Tên lane; Branch: Tạo `feat/<name>` từ một branch gốc, hoặc Dùng branch có sẵn; Database: Fork kèm dữ liệu, Chỉ schema hoặc Database trống; Chạy lane khi đã sẵn sàng	Tạo từ branch hiện tại, Fork kèm dữ liệu, bật chạy lane
Clone vào <directory>	URL repository, Tên thư mục, Branch, Clone vào (khi có nhiều thư mục park), các bước trong Sau khi clone	bật mọi bước trừ Chạy site khi đã sẵn sàng
Xoá <site>?	những gì devkit cho biết sẽ bị xoá (thư mục, lane, route Caddy), Xoá database, Chuyển thư mục vào Thùng rác thay vì xoá vĩnh viễn, và gõ tên site để xác nhận. Khi có phần việc chỉ tồn tại trên máy này: Vẫn xoá và mất phần việc này	bật Thùng rác, tắt xoá database
Xoá lane <lane>?	những gì `lane rm --dry-run` báo, Giữ database, Xoá luôn branch local; khi có phần việc chưa lưu: Vẫn xoá và bỏ phần việc này	tắt cả hai
Ẩn <site> khỏi devkit?	không hỏi gì: chỉ nói site và các lane của nó sẽ dừng, trên đĩa không có gì thay đổi
Snapshot <database>	Tên (để trống: thời điểm hiện tại); hiện các snapshot đã có
Khôi phục <database>	snapshot nào, Tạo snapshot database hiện tại trước; Những gì sẽ diễn ra liệt kê ba bước	bật snapshot an toàn
Đặt lại database của <lane>?	Schema và dữ liệu hoặc Chỉ schema, Tạo snapshot database của lane trước khi đặt lại	schema và dữ liệu, bật snapshot
Xoá snapshot <name>?	một bước xác nhận: snapshot đã xoá không lấy lại được
Xdebug · <site>	chế độ (off, debug, coverage, profile); với debug là cách bắt đầu một phiên (trigger, client host, port 9003, path mapping); những site bị ảnh hưởng khi đổi container	debug khi đang off
Engine web server · <site>	artisan hoặc caddy, Những gì thay đổi (URL, PHP, `DB_HOST`, `REDIS_HOST`, port) và Yêu cầu (đã cài PHP, có port trống; hoặc service Caddy và PHP, mount cùng đường dẫn, chứng chỉ)	engine còn lại
Template .env · <site>	Template / .env đã render, Hiện mật khẩu và secret, Biến · bấm để chèn, Lưu, Lưu và chạy lại site	ẩn secret
Thêm vào extensions · <site>	URL repository, Tên thư mục, Branch	branch mặc định của repository
Log · <site>	mỗi nguồn một tab, Lọc dòng, Theo dõi, Sao chép các dòng đang hiện, Hiện trong Finder	200 dòng cuối, đang theo dõi
Doctor · <site>	từng mục kiểm tra kèm trạng thái và gợi ý, Sao chép báo cáo, Chạy lại

App xác nhận như thế nào

Hỏi devkit trước. Sheet có tính phá huỷ chạy lệnh mà không có --yes (hoặc với --dry-run) và hiện đúng câu trả lời của devkit: phần việc chưa commit, database sẽ bị xoá, các bước khôi phục.
Hỏi lại ngay trước khi làm. Nếu câu trả lời đã thay đổi trong lúc đó (có người commit, có snapshot mới, một agent đã chạy site), app không làm gì cả và sheet báo Đã có thay đổi kể từ lần bạn xem trước kèm câu trả lời mới. Mọi ô "vẫn …" đều bị bỏ chọn.
Chỉ khi đó app mới truyền --yes hoặc --force.

Engine mặc định, hậu tố tên miền và khoảng port trong Cài đặt cũng làm như vậy, qua --dry-run.

Lanes

Mọi lane nằm dưới site của nó, với các cột giống Sites. Lane mới… ở trên cùng là một menu với mỗi site một mục, và mỗi nhóm site có Lane mới… riêng.

Stacks

Thêm stack… chọn một thư mục compose. Mỗi stack là một thẻ có Hiện trong Finder, Chạy, Chạy lại, Dừng…, Hộp thư ↗ và số service bị ẩn theo label, cùng một bảng service: Service, Vai trò, Image, Port, Trạng thái và với mỗi service là Chạy lại, Dừng… hoặc Chạy, và Log. Dừng… cảnh báo rằng các site đang chạy có thể dùng database hoặc Redis của stack sẽ ngừng hoạt động. Dừng cả stack là docker compose down (xoá container, giữ volume); dừng một service là docker compose stop.

PHP

Trên cùng có Quét lại và Thêm binary…. Tiếp theo:

PHP mặc định: php trong PATH hoặc một trong các phiên bản, áp dụng ngay.
PHP trên máy: mỗi binary một thẻ (phiên bản, đường dẫn, site, Xdebug, extension). Panel của binary đang chọn có Mở php.ini, Sao chép đường dẫn, Đặt làm mặc định, Xdebug hoặc cách cài Xdebug, Dùng bởi, Extension đã nạp và composer check-platform-reqs cho từng site dùng nó, cùng Kiểm tra site khác.
Cũng trong lưới đó, thẻ chưa cài cho phiên bản mà một site cần, kèm lệnh cài và Sao chép lệnh. App không bao giờ tự chạy lệnh này.
Vị trí quét: mỗi đường dẫn có ô bật/tắt, nguồn gốc (Homebrew, Theo hệ thống, phpenv, Đã thêm…) và nút gỡ; Thêm vị trí; Đặt lại mặc định….
PHP trong container: các service PHP-FPM của stack kèm phiên bản, image, trạng thái, các site caddy chạy trên đó và Xdebug (mọi site); đổi mục này sẽ mở một sheet nêu tên các site bị ảnh hưởng.

Templates

Mỗi site một dòng: template đã được lưu hay vẫn là tạo từ .env (chưa lưu), những lane nào dùng nó, nó có render được không (mọi biến đều có giá trị), và Sửa…, mở sheet template .env. Tab .env đã render của sheet là devkit template render --file trên bản nháp của bạn, nên bạn thấy kết quả thật trước khi lưu.

Cài đặt

Engine web server mặc định: artisan hoặc caddy. Chọn một engine sẽ mở sheet liệt kê các site đang chạy sẽ bị dừng.
Khoảng port: Từ, Đến, Áp dụng…, và số port đang dùng.
Hậu tố tên miền: site caddy được phân giải thành <site>.<suffix>; Áp dụng….
Chứng chỉ: CA của mkcert đã được tin cậy chưa và đã cấp bao nhiêu chứng chỉ cho site; Tin cậy… và Kiểm tra lại.
Hosts: khối của devkit trong /etc/hosts đã cập nhật chưa; Đồng bộ trong Terminal… và Kiểm tra lại.
Binary PHP: phần tóm tắt kèm Quản lý trong PHP → và Thêm đường dẫn….
Doctor: báo cáo đầy đủ cho máy và từng site, Sao chép báo cáo, Chạy lại.
Site đã ẩn: mỗi site kèm Hiện lại.
App này: Binary devkit, Editor, Mở devkit khi đăng nhập và Ngôn ngữ, mô tả ở dưới.

Tin cậy… và Đồng bộ trong Terminal… không bao giờ chạy bên trong app, vì chúng cần mật khẩu của bạn. App hỏi Chạy devkit trust trong Terminal?, ghi một script nhỏ tự xoá sau khi chạy, dùng devkit, PATH và thư mục cấu hình của app, rồi mở nó trong terminal. Khi xong, quay lại app và bấm Kiểm tra lại.

App này

Binary devkit: devkit nào app sẽ chạy, áp dụng từ lần mở tới. Để trống nghĩa là bản nằm trong app, rồi tới bản đầu tiên trong PATH. Tuỳ chọn khởi động --devkit và DEVKIT_BIN được ưu tiên hơn. devkit hiện dùng cho biết bản nào đang được dùng.
Editor: App dùng gì để mở thư mục site khi bạn chọn Mở trong editor. macOS: Mặc định (hệ thống) (Visual Studio Code nếu đã cài, nếu không thì Finder), một editor đã cài, hoặc bất kỳ app nào qua Chọn app…. Linux: một lệnh, chạy với thư mục làm tham số (tách như shell; ~ và $VAR được mở rộng trong tên chương trình); để trống nghĩa là code nếu có trong PATH, nếu không thì mở thư mục trong trình quản lý file. Trên Linux, DEVKIT_EDITOR được ưu tiên hơn.
Mở devkit khi đăng nhập: macOS thêm một login item (System Settings có thể yêu cầu bạn duyệt ở General → Login Items; app có nút Mở mục đăng nhập). Linux ghi file ~/.config/autostart/vn.webpress.devkit.desktop.
Ngôn ngữ: Theo hệ thống, English hoặc Tiếng Việt, áp dụng từ lần mở tới; Mở lại ngay khởi động lại app. Theo hệ thống đi theo các ngôn ngữ ưu tiên trên macOS, và theo LANGUAGE, LC_ALL, LC_MESSAGES, LANG trên Linux. Trên Linux, nút Menu của cửa sổ cũng có lựa chọn này. Những gì chính devkit nói (thông báo, lỗi, gợi ý và câu hỏi xác nhận) vẫn bằng tiếng Anh, đúng như CLI viết.

MCP

Kết nối agent: mỗi agent một nút (Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code · Copilot, Claude Desktop, Khác (stdio)) kèm lệnh terminal hoặc file cấu hình và Sao chép. Với các agent cấu hình theo từng dự án (Claude Code, Gemini CLI, Cursor, VS Code), Ghi vào dự án… cho bạn chọn thư mục dự án và gộp mục cấu hình vào file config của nó, có giữ bản sao lưu.
Đang kết nối: từng devkit mcp đang chạy kèm agent, pid, thời điểm bắt đầu và số lần gọi.
Tool: mọi tool theo nhóm, tool có tính phá huỷ có nhãn confirm.
Audit log: các lần gọi gần nhất (thời gian, agent, tool, đối tượng, tham số, kết quả), mới nhất ở trên, tải lại mỗi khi agent gọi; Làm mới và Hiện trong Finder.

Chi tiết có trong AI agent (MCP).

Khác biệt giữa macOS và Linux

	macOS	Linux
Vị trí	panel trên menu bar	menu tray, hoặc cửa sổ panel khi không có tray
Phím tắt trong panel `…`	`⌘O` `⌘E` `⌘T` `⌘C`	`Ctrl`+`O`/`E`/`T`/`C`
Tin cậy và đồng bộ hosts	mở trong Terminal.app	mở trong `$TERMINAL`, nếu không thì cái đầu tiên có trong x-terminal-emulator, gnome-terminal, ptyxis, kgx, konsole, xfce4-terminal, alacritty, kitty, xterm
Mở terminal tại đây	Terminal.app	cùng terminal như trên
Nhãn thư mục và terminal	Hiện trong Finder, Đồng bộ trong Terminal…, Chạy devkit trust trong Terminal?	Hiện trong thư mục, Đồng bộ trong terminal…, Chạy devkit trust trong terminal?
Cài đặt editor	hộp chọn app	một lệnh; `DEVKIT_EDITOR` được ưu tiên
Mở khi đăng nhập	login item	file autostart XDG
Cài đặt ngôn ngữ	Cài đặt → App này	Cài đặt → App này, và Menu của cửa sổ
Nơi lưu cài đặt app	macOS defaults (`vn.webpress.devkit`)	`~/.config/devkit-app/settings.json` (`DEVKIT_APP_CONFIG`)
Sáng hoặc tối	theo macOS	theo desktop; `DEVKIT_APP_THEME=light\|dark` ép một chế độ
Lệnh cài PHP	`brew install php@X.Y`	apt, dnf, pacman/AUR hoặc Homebrew, tuỳ theo `/etc/os-release`
Cảnh báo `.local`	mDNS	Avahi (mDNS)
Log của app	`~/Library/Logs/devkit/devkit-app.log`	`~/.local/state/devkit/devkit-app.log`

Trên Linux, nếu bạn thoát khi devkit vẫn đang chạy một thay đổi, app sẽ chờ thay đổi đó xong (Đang chờ để thoát); thoát lần nữa để dừng ngay.

Tuỳ chọn khởi động và log của app

Cả hai app đọc PATH của login shell một lần khi khởi động ($SHELL -ilc) và truyền cho devkit, nên docker, git, composer, pnpm và PHP của Homebrew được tìm thấy giống như trong terminal của bạn. Nếu app không tìm thấy một công cụ, hãy kiểm tra công cụ đó chạy được trong một cửa sổ terminal mới, rồi thoát và mở lại app.

Tuỳ chọn	Biến	Tác dụng
`--devkit <path>`	`DEVKIT_BIN`	binary devkit sẽ chạy
`--config-home <dir>`	`DEVKIT_CONFIG_HOME`	chạy devkit với `XDG_CONFIG_HOME=<dir>`: một bộ site và cài đặt riêng, tiện để thử nghiệm
`--open-manager`		mở cửa sổ quản lý khi khởi động
`--no-tray` (Linux)		dùng cửa sổ panel thay cho tray
	`DEVKIT_APP_LOG`	nơi app ghi log những gì nó đã chạy và kết quả trả về

Trên macOS, truyền tuỳ chọn bằng open /Applications/devkit.app --args --open-manager và biến bằng open --env NAME=value. open devkit.app --args -AppleLanguages '(vi)' mở app bằng tiếng Việt một lần. Log của app ghi lại các dòng lệnh và câu trả lời, đã bỏ thông tin đăng nhập trong URL; đây là thứ đầu tiên nên xem khi một nút không làm đúng như bạn mong đợi, và là thứ nên gửi kèm khi bạn cần hỗ trợ.