Tài liệu gốc 06 7 phútTiếng Việt + English

running_the_code/04_sandboxing.mdXem bản gốc

Ngôn ngữ bài đọc

Bản dịch tiếng Việt

Bản dịch đầy đủ theo đúng cấu trúc tài liệu; code, liên kết và định danh kỹ thuật được giữ nguyên.

Hộp cát - Không gian làm việc bị cô lập, `--repo` & sự hỗ trợ của git

Theo mặc định (SANDBOX_MODE=none) bash chạy như một quy trình con máy chủ và các công cụ tệp chỉnh sửa trực tiếp thư mục làm việc của bạn. Đặt Chế độ hộp cát và phạm vi công cụ toàn bộ của agent — công cụ tệp và bash — di chuyển vào một Không gian làm việc biệt lập, trong khi các thành phần lạ của chính bộ decode (phiên, bộ nhớ, nhật ký, tệp quyền) vẫn nằm trong thư mục khởi chạy của bạn (ADR-0012):

`SANDBOX_MODE`	Công cụ chạy ở đâu	Không gian làm việc
`none` (mặc định)	quy trình con máy chủ + công cụ tệp trực tiếp	không có - không thay đổi, không cần Docker/Modal
`docker`	một thùng chứa cục bộ liên tục theo phiên	`/workspace` là kết nối liên kết trực tiếp của máy chủ `.decode/sandbox/`
`modal`	một phiên liên tục từ xa `modal.Sandbox`	không có gì chạy trên máy của bạn; `/workspace` được tải lên bootstrap khi khởi chạy và xuất trở lại khi thoát / `/ship`

Cả hai chế độ đều là một trình thực thi hợp nhất với ngữ nghĩa fresh-exec: hệ thống tệp vẫn tồn tại trong các lệnh gọi, nhưng cd/export đừng (xâu chuỗi chúng: cd /workspace/app && …). Hộp cát bắt đầu háo hức khi khởi chạy (a sandbox:<mode> phân đoạn biểu ngữ) và bash vẫn được kiểm soát chính xác như trước — hộp cát được bảo vệ chuyên sâu bên dưới lời nhắc phê duyệt.

thiết lập

Ở đây không cần gì cho những bài học đầu tiên — 01_install_and_usage.md làm cho agent chạy với SANDBOX_MODE=none. Thêm phần phụ trợ bạn muốn:

Chế độ	Điều kiện tiên quyết	Cài đặt/xác thực
`docker`	Docker chạy cục bộ	docker.com, sau đó khởi động Docker Desktop
`modal`	token tài khoản phương thức trong process env	`modal token set --token-id … --token-secret …` (viết `~/.modal.toml`). Đây không phải là cài đặt decode — đặt chúng vào `.env` không làm gì cả

Env var	Nó dùng để làm gì
`SANDBOX_MODE`	`none` (mặc định) · `docker` · `modal`
`SANDBOX_REPO`	repo được sao chép vào Không gian làm việc; `--repo` ghi đè nó
`SANDBOX_WORKSPACE_DIR`	thư mục máy chủ là Workspace (mặc định `.decode/sandbox`)
`SANDBOX_IMAGE`, `SANDBOX_TIMEOUT_S`, `SANDBOX_GIT_USER_NAME`, `SANDBOX_GIT_USER_EMAIL`	điều chỉnh - xem bên dưới
`SANDBOX_GIT_TOKEN`	chọn tham gia: cho phép model đẩy / mở PR từ bên trong Không gian làm việc (bên dưới). PAT có phạm vi repo chi tiết của GitHub.

Làm việc trên bất kỳ repo nào và lấy lại một nhánh

SANDBOX_MODE=docker decode --repo git@github.com:you/project.git
#   … the agent reads, edits, and runs bash entirely inside /workspace …
/ship          # or just quit — decode pushes a `decode/<session-id>` branch back to the repo

--repo <url-or-path> (hoặc SANDBOX_REPO; thêm --local để sao chép cục bộ nhanh) sao chép tại cam kết HEAD sử dụng thông tin đăng nhập git xung quanh của bạn. Một repository kém sẽ chuyển thành Không gian làm việc trống với một dòng thân thiện; --repo không có chế độ hộp cát là một lỗi cấu hình thân thiện. Hoạt động headless quá: SANDBOX_MODE=docker decode run --repo <url> "<task>". Nó chỉ sao chép vào một không gian làm việc trống — một vùng được điền .decode/sandbox được sử dụng lại, không bao giờ được sao chép lại (điều đó sẽ loại bỏ công việc đang thực hiện), vì vậy --repo đối với Không gian làm việc còn sót lại sẽ bị bỏ qua và không có origin để đẩy tới. rm -rf .decode/sandbox để buộc một bản sao mới.
Trả lại khi xuất cảnh hoặc /ship - decode cam kết bất kỳ công việc mô hình nào không được cam kết (các cam kết mô hình được giữ nguyên, không bao giờ viết lại), điểm a decode/<session-id> phân nhánh ở kết quả và đẩy nó. Mọi lệnh git đều chạy phía máy chủ, với thông tin xác thực git xung quanh của bạn — quay lại không đặt thông tin xác thực nào vào hộp cát (điều đó giữ cho dù bạn có đặt hay khôngSANDBOX_GIT_TOKEN). Một lần đẩy không thành công vẫn khiến chi nhánh địa phương .decode/sandbox và đặt tên cho nó; một Workspace không thay đổi sẽ bị bỏ qua.
Bộ bảo vệ khởi động — một chương trình phụ trợ được chọn không có sẵn bị lỗi với một dòng thân thiện (Docker daemon bị hỏng hoặc bị thiếu modal token set bằng chứng xác thực), trong REPL và cả máy bay headless trước chuyến bay.
Sự trung thực trong cách ly — docker là ranh giới cho hành vi sai trái vô tình (kernel được chia sẻ trên Linux; VM của Docker Desktop thêm một kernel trên macOS); modal là bậc thang cho mã thực sự không đáng tin cậy (không có gì thực thi trên máy của bạn). gVisor/Kata là các bản nâng cấp daemon-config không mã; xem bảng cách ly của ADR-0011.

Điều chỉnh (tất cả đều tùy chọn, được ghi lại trong .env.example): SANDBOX_IMAGE (mặc định ghcr.io/astral-sh/uv:python3.12-bookworm-slim — python + uv được cài đặt sẵn; mỗi phần phụ trợ thêm git + the gh CLI, do đó, mô hình có thể cam kết, Đẩy, và mở PR — docker cài đặt chúng mỗi phiên (~20 giây), phương thức sẽ đưa chúng vào một lớp hình ảnh được lưu trong bộ nhớ đệm), SANDBOX_TIMEOUT_S (tuổi thọ phương thức), SANDBOX_GIT_USER_NAME/_EMAIL (danh tính cam kết trong Workspace), SANDBOX_GIT_TOKEN (bên dưới).

token git hộp cát (`SANDBOX_GIT_TOKEN`)

Hỗ trợ lại (ở trên) cần không thông tin xác thực trong hộp cát - nó sẽ đẩy phía máy chủ. SANDBOX_GIT_TOKEN là lựa chọn tham gia cho yêu cầu lớn hơn: để mô hình chạy git push / gh pr create từ bên trong Không gian làm việc. Đặt nó và token được đưa trực tiếp vào env của Công nhân dưới dạng GITHUB_TOKEN trong cả hai chương trình phụ trợ, cộng với trình trợ giúp thông tin xác thực git để HTTPS đẩy và gh xác thực (ADR-0016) — cơ chế chính xác, bằng chứng trực tiếp và mọi trường hợp tiêu cực: 06_credentials.md Phần 2.

Một quy trình trong hộp cát có thể đọc $GITHUB_TOKEN - cũng là một agent được tiêm nhanh chóng. Sử dụng ** PAT chi tiết, có phạm vi repo, có thể thu hồi và thu hồi nó khi bạn hoàn tất. Để biến không được đặt và hộp cát không có thông tin xác thực nào cả - việc chuyển giao lại vẫn gửi chi nhánh của bạn.

decode được sử dụng để ẩn token này đằng sau một sidecar mitmproxy (Proxy thông tin). Nó đã bị xóa (ADR-0016): nó chỉ hoạt động ở một trong ba chế độ sandbox, lối ra dù sao cũng hợp tác (curl --noproxy '*' đi bộ xung quanh nó), và máy móc có giá cao hơn mức bảo vệ. Giờ đây đã có một cơ chế, cả hai phụ trợ — một câu chuyện bảo mật đúng như đã viết.

Khắc phục sự cố

Những người bảo vệ hộp cát kiểm tra chỉ sự hiện diện và khai hỏa trong cả REPL và thiết bị headless trước chuyến bay:

Bạn thấy gì	Ý nghĩa của nó	Sửa chữa
`Decode: SANDBOX_MODE=docker but the Docker daemon is not reachable`	`docker` được chọn với Docker đã dừng	khởi động Docker Desktop hoặc đặt `SANDBOX_MODE=none`.
`Decode: SANDBOX_MODE=modal but Modal credentials are missing`	không có token tài khoản phương thức nào trong quá trình env	`modal token set …`. `.env` không làm gì cho những điều này.
`Decode: --repo/SANDBOX_REPO clones a repo into the isolated sandbox Workspace …`	`--repo` được thông qua với `SANDBOX_MODE=none`	đặt `SANDBOX_MODE=docker` hoặc `modal`, hoặc thả `--repo`.
`--repo` dường như bị bỏ qua, và không có `origin` để đẩy tới	Không gian làm việc đã được điền sẵn — decode không bao giờ sao chép lại công việc đang thực hiện	`rm -rf .decode/sandbox` để buộc một bản sao mới.
`cd` hoặc `export` từ một `bash` cuộc gọi không áp dụng cho	ngữ nghĩa của Fresh-exec: hệ thống tập tin vẫn tồn tại, quá trình không	xâu chuỗi chúng: `cd /workspace/app && …`.

Mọi thứ khác — khóa nhà cung cấp, giới hạn tỷ lệ, kỹ năng, phiên — đều có trong 00_troubleshooting.md.

Đi xa hơn

Hướng dẫn xác thực từ đầu đến cuối — bộ token, không đặt token và mọi trường hợp phủ định: 06_credentials.md.
Chạy một agent sandboxed headless (decode run --repo …): 03_runtime.md.
Di chuyển toàn bộ agent (không chỉ các công cụ của nó) lên đám mây: 07_infra.md.