Develop local
Trong trang này
Develop local dùng hai process độc lập ở hai terminal. Bạn sở hữu watcher của app; CLI sở hữu Development session và tunnel dẫn về máy bạn. Sota CLI không bao giờ start, restart hay kill process của bạn — kể cả khi session dừng.
# terminal 1 — watcher của app
npm run dev
# terminal 2 — Development session và tunnel
npm run dev:sota # tương đương: sota devTự chạy watcher
Chạy npm run dev. Trong project scaffold có cả backend lẫn native UI, chỉ một script này đã chạy cả hai: concurrently khởi động watcher backend và watch build UI song song, gắn nhãn backend và ui, kèm --kill-others để một bên crash thì dừng cả cặp thay vì để lại nửa stack đang chạy.
Mở Development
Chạy sota dev, chọn organization và workspace, rồi giữ process chạy. CLI chuẩn bị mọi thứ ở local trước — compile manifest, kiểm tra output frontend đã build, mở tunnel transport — rồi mới publish session trong một lần commit. Nếu bước chuẩn bị lỗi, không có gì được tạo trên server.
Iterate an toàn
CLI theo dõi mọi file mà manifest đã compile được dựng lên từ đó — chính manifest, JSON Schema, file locale, native asset và nội dung skill được inline — rồi re-sync vào session cá nhân của bạn khi có thay đổi. Lỗi compile chỉ in diagnostics và giữ nguyên manifest last-known-good. Heartbeat mỗi 15 giây gia hạn lease của session.
Dừng sạch
Chạy sota dev stop, hoặc bấm Ctrl-C trong terminal sota dev. Development app biến mất và Core lên lịch cleanup data. Process frontend/backend của bạn vẫn chạy — CLI nói rõ điều đó khi thoát.
Chạy riêng UI và backend#
npm run dev chỉ là lớp bọc tiện lợi cho hai script vẫn tồn tại độc lập. Hãy chạy riêng khi bạn muốn restart một nửa mà không đụng nửa kia, gắn debugger vào đúng một bên, hoặc — quan trọng nhất — khi backend của bạn không phải process Node.js.
| Script | Thực chất chạy gì | Ghi chú |
|---|---|---|
npm run dev | concurrently --kill-others --names backend,ui "tsx watch src/backend/server.ts" "sota contracts ensure && vite build --watch" | Cả hai nửa cùng lúc. Project chỉ có backend hoặc chỉ có UI thì rút gọn về đúng nửa đó. |
npm run dev:backend | tsx watch src/backend/server.ts | HTTP service của app, tự restart khi source đổi. Nghe ở PORT, mặc định 8787. |
npm run dev:ui | sota contracts ensure && vite build --watch | Là watch build, không phải dev server. Nó làm mới App UI type contract rồi build lại dist/ui/app.js và dist/ui/app.css mỗi lần thay đổi. |
npm run dev:sota | sota dev | Development session, đồng bộ manifest và tunnel. Độc lập với hai script trên. |
Native UI chạy bên trong host SotaAgents, không phải trên localhost. dev:ui chỉ cần giữ module đã build trên đĩa luôn mới; tunnel phục vụ đúng những bytes đó cho nền tảng — nhờ vậy cùng bộ file chạy y hệt khi được đóng gói vào artifact đã deploy.
Dùng backend runtime của riêng bạn#
Scaffold dùng TypeScript và Express vì đó là thứ phổ biến dễ hiểu, không phải vì nền tảng bắt buộc. Contract giữa SotaAgents và backend của bạn chỉ là HTTP thuần cộng một token đã verify, nên service viết bằng Go, Python, Java hay Rust đều là app backend hạng nhất. Một trong các system app của SotaAgents là service FastAPI verify đúng invocation token đó bằng Python, với cùng endpoint JWKS của Core.
Trong trường hợp đó bạn đơn giản là không dùng các script backend Node. Khởi động service theo cách của stack bạn, giữ npm run dev:ui cho native UI nếu app có UI, và trỏ overlay local vào cổng service của bạn đang nghe:
# terminal 1 — backend của bạn, bằng ngôn ngữ của bạn
uvicorn app.main:app --reload --port 8787
# terminal 2 — watch build native UI (chỉ khi app có UI)
npm run dev:ui
# terminal 3 — Development session
sota devsota dev resolve Local Backend Endpoint theo thứ tự: flag --local-url, rồi environments.local.service.baseUrl trong manifest, rồi endpoint bạn dùng lần gần nhất (ghi nhớ trong .sota/dev.json). Trong terminal tương tác, CLI sẽ hỏi nếu không có nguồn nào; ngược lại nó fail với LOCAL_BACKEND_UNAVAILABLE. Sau đó CLI poll endpoint đó khoảng mỗi giây và in [backend] available hoặc [backend] unavailable. Kiểm tra này chỉ mang tính thông báo — nó không chặn việc publish session, nên backend tạm sập không làm mất Development app của bạn.
Nó thuộc một developer và một workspace. Chạy lại sota dev chỉ thay session cũ của chính bạn; đây không phải Staging dùng chung. Staging và Production không bao giờ phụ thuộc tunnel — chúng gọi thẳng backend bạn host.