docs: add OpenCode integration guide by xie-guangzhen · Pull Request #689 · TencentCloud/CubeSandbox

xie-guangzhen · 2026-07-01T02:46:29Z

Summary

Adds an OpenCode integration contribution for #644, covering one terminal coding-agent direction end to end.

Add bilingual integration docs under docs/guide/integrations/opencode.md and docs/zh/guide/integrations/opencode.md
Add examples/opencode-integration/ with a Docker template, template build script, environment sample, Python runner, and bilingual README
Document API key injection, network/egress policy, snapshot-based session persistence, and troubleshooting

Validation

chmod +x examples/opencode-integration/build-template.sh
python3 -m py_compile examples/opencode-integration/run_opencode.py
bash -n examples/opencode-integration/build-template.sh
git diff --check

Related Issue

Fixes #644

Assisted-by: OpenCode:codewiz/gpt-5.5

cubesandboxbot · 2026-07-01T02:53:48Z

+./build-template.sh
+```
+
+The script prints a `template_id`. Put it in `CUBE_TEMPLATE_ID`.


Factual inaccuracy: build-template.sh does not print a template_id. It prints a cubemastercli tpl create-from-image … command and tells the user to "Set CUBE_TEMPLATE_ID to the returned template_id." The template_id is obtained only after running that cubemastercli command separately — not from build-template.sh itself. A user following the guide literally will run the script, see no template ID, and be confused.

Same issue in the Chinese translation (docs/zh/guide/integrations/opencode.md, line 41).

cubesandboxbot · 2026-07-01T02:53:49Z

+Copy the environment file:
+
+```bash
+cp examples/opencode-integration/.env.example examples/opencode-integration/.env


Path inconsistency: The Build section (line 37) does cd examples/opencode-integration, placing the user inside that directory. This Configure Secrets section then uses project-root-relative paths (cp examples/opencode-integration/…), which will fail with "No such file or directory" when followed sequentially. Either use the short form cp .env.example .env here, or have the Build section use absolute paths so the user stays at the project root.

Same issue in the Chinese translation (docs/zh/guide/integrations/opencode.md, line 50).

cubesandboxbot · 2026-07-01T02:53:50Z

+        console.print(result.stdout)
+    if result.stderr:
+        console.print(result.stderr, style="yellow")
+    if getattr(result, "exit_code", 0) not in (0, None):


Silent success on missing/None exit_code: getattr(result, "exit_code", 0) defaults to 0 (success) when the attribute is missing, so a future SDK change that renames or removes exit_code would silently make every command appear successful. Additionally, None (which the e2b library can return on timeout or interruption) is treated as success via the not in (0, None) check, hiding real failures.

Consider getattr(result, "exit_code", -1) or accessing the attribute directly.

cubesandboxbot · 2026-07-01T02:53:51Z

+    parser.add_argument("--network", choices=["default", "no-internet"], default="default")
+    args = parser.parse_args()
+
+    if not args.template:


Return value of require_env discarded: require_env("CUBE_TEMPLATE_ID") both validates and returns the value, but the return is discarded. Line 98 then accesses os.environ["CUBE_TEMPLATE_ID"] directly with a bare key lookup, which raises a KeyError instead of the descriptive SystemExit. Assign the return value to args.template here.

cubesandboxbot · 2026-07-01T02:53:53Z

+        python3 \
+        python3-pip \
+        ripgrep \
+    && npm install -g opencode-ai \


Unpinned dependencies: Both the base image (sandbox-code:latest) and opencode-ai (no version) are unpinned. A breaking change in either can silently break the template. Consider pinning to a specific base image digest and an explicit npm version (e.g., opencode-ai@x.y.z).

Also add && npm cache clean --force to avoid carrying 10–50+ MB of npm cache into the final image.

cubesandboxbot · 2026-07-01T02:54:29Z

+./build-template.sh
+```
+
+The script prints a `template_id`. Put it in `CUBE_TEMPLATE_ID`.


Factual inaccuracy: build-template.sh does not print a template_id. It prints a cubemastercli tpl create-from-image … command and instructs the user to "Set CUBE_TEMPLATE_ID to the returned template_id." The template_id is obtained only after the user runs that separate cubemastercli command — not from build-template.sh itself. A user following the guide literally will run the script, see no template ID printed, and be confused.

The same issue exists in the Chinese translation (docs/zh/guide/integrations/opencode.md, line 41).

cubesandboxbot · 2026-07-01T02:54:30Z

+Copy the environment file:
+
+```bash
+cp examples/opencode-integration/.env.example examples/opencode-integration/.env


Path inconsistency: The Build section (line 37) does cd examples/opencode-integration, placing the user inside that directory. This Configure Secrets section then uses project-root-relative paths (cp examples/opencode-integration/…), which will fail with "No such file or directory" when followed sequentially. Either use the short form cp .env.example .env here, or have the Build section use an absolute path so the user stays at the project root.

Same issue in the Chinese translation (docs/zh/guide/integrations/opencode.md, line 50).

cubesandboxbot · 2026-07-01T02:54:31Z

+        console.print(result.stdout)
+    if result.stderr:
+        console.print(result.stderr, style="yellow")
+    if getattr(result, "exit_code", 0) not in (0, None):


Silent success on missing/None exit_code: getattr(result, "exit_code", 0) defaults to 0 (success) when the attribute is missing, so a future SDK change that renames or removes exit_code would silently make every command appear successful. Additionally, the not in (0, None) check means a None exit_code (which the e2b library can return on timeout or interruption) is also treated as success, hiding real failures.

Consider getattr(result, "exit_code", -1) or accessing the attribute directly and letting it fail loudly if absent.

cubesandboxbot · 2026-07-01T02:54:31Z

+    parser.add_argument("--network", choices=["default", "no-internet"], default="default")
+    args = parser.parse_args()
+
+    if not args.template:


Return value of require_env discarded: require_env("CUBE_TEMPLATE_ID") both validates existence and returns the value, but the return is discarded. Line 98 then accesses os.environ["CUBE_TEMPLATE_ID"] directly with a bare key lookup, which would raise a KeyError instead of the descriptive SystemExit message. Assign the return value back to args.template here.

cubesandboxbot · 2026-07-01T02:54:32Z

+        python3 \
+        python3-pip \
+        ripgrep \
+    && npm install -g opencode-ai \


Base image uses latest tag and opencode-ai is unpinned: Both the base image (cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest) and the globally installed npm package (opencode-ai with no version) are unpinned. A breaking change in either can silently break the template without any code changes. Consider pinning to a specific base image digest and an explicit npm version (e.g., npm install -g opencode-ai@x.y.z).

Additionally, add && npm cache clean --force to this RUN layer to avoid carrying 10–50+ MB of unnecessary npm cache data into the final image.

fslongjin · 2026-07-06T07:24:52Z

Refs #644 (this is a multi-participation issue, please use Refs instead of Fixes)

fslongjin · 2026-07-10T07:50:00Z

Hello, thank you for your contribution! Since we have a large number of participants in this event, to speed up the PR review process, could you please attach some screenshots and logs (both are needed) showing the verification process and results for this PR? Thank you for your participation!

fslongjin

Hello~Can you add more test results/screenshots which can prove this feature can work in a REAL CubeSandbox cluster?

docs: add OpenCode integration guide

9f05216

Assisted-by: OpenCode:codewiz/gpt-5.5

xie-guangzhen requested a review from tinklone as a code owner July 1, 2026 02:46

cubesandboxbot Bot reviewed Jul 1, 2026

View reviewed changes

fslongjin added the 犀牛鸟 label Jul 6, 2026

fslongjin requested changes Jul 12, 2026

View reviewed changes

Uh oh!

Conversation

xie-guangzhen commented Jul 1, 2026

Summary

Validation

Related Issue

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

cubesandboxbot Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

fslongjin commented Jul 6, 2026

Uh oh!

fslongjin commented Jul 10, 2026

Uh oh!

fslongjin left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants