docs: add minimal container / agent sandbox instructions to AGENTS.md by lidge-jun · Pull Request #2832 · lidge-jun/opencodex

lidge-jun · 2026-08-28T16:10:50Z

Summary

Adds a ## Minimal containers and agent sandboxes section to AGENTS.md so future agent runs and fresh dev containers do not rediscover the same setup facts. Written generically — applies to Cursor Cloud, devcontainers, CI images, and similar sandboxes, not one product.
Documents that such images often ship Node but not Bun, with the exact install/bootstrap commands (bun install at the root and in gui/).
Documents how to run the proxy (ocx start --port), where the admin token is written, and which endpoints prove it is up.
Records the five bun run test failures that are environment-only in such containers (three need a running systemd init — PID 1 is typically tini or another minimal init; two depend on filesystem mtime granularity), so they are not re-investigated as regressions.
No runtime/source code changes.

This replaces an earlier revision of this branch that added .cursor/environment.json; per maintainer feedback, this knowledge belongs in AGENTS.md instead.

Verification

Ran on a fresh Cloud Agent VM while setting up the environment:

Installed Bun 1.4.0 (matches the pinned bun dependency) via the official installer; bun install (root) and bun install (gui/) resolved from bun.lock.
bun run typecheck — passed (tsc --noEmit, strict).
bun run test — 15480 pass, 16 skip, 5 fail; the 5 failures are exactly the environment-only set now documented in AGENTS.md (clean tree, no code changes).
cd gui && bun run build — Vite 8 production build succeeded (261 modules).
Started the proxy (ocx start --port 8899): GET /healthz → {"status":"ok","version":"2.35.0",...}; authenticated GET /api/config|settings|models → 200; unauthenticated → 401; GET / serves the dashboard (screenshot below).

opencodex dashboard overview, proxy online v2.35.0

Checklist

Scope stays focused and avoids unrelated cleanup.
Docs or release notes were updated when needed. (This PR is the docs update.)
Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (Docs only; no secrets — the token path is documented, not its value.)

_{To show artifacts inline, enable in settings.}

Summary by CodeRabbit

Documentation
- Added guidance for setting up minimal development containers and agent sandboxes.
- Documented proxy startup and access to health, root, and management endpoints.
- Listed known environment-specific test failures and clarified which results do not require further investigation.

release: promote dev into main for v2.32.1

# Conflicts: # package.json

[WRONG BRANCH] merge dev into main for the v2.33.0 release

Promotes the dev integration line onto main. The resulting tree is byte-identical to origin/dev, including package.json at 2.34.0. The package.json conflict is resolved to dev's side, NOT to main's stale 2.33.0. Earlier promotions (#2553, #2507) kept the target's version so the release bump would land on its own "release: vX.Y.Z" commit. That is no longer legal: this very delta adds tests/release-version-line.test.ts, which fails when the in-tree version sits behind the highest release tag. With v2.34.0-preview.20260827 now published, 2.33.0 orders behind it, so a promotion carrying the stale line turns CI red on every shard that runs the suite. The consequence for the release step is that scripts/release.ts skips the bump (release.ts:568, currentVersion === version), so v2.34.0 gets tagged on this merge commit rather than on a separate release commit. The workflow creates the tag itself after publishing and validates expected-sha against the checked-out commit, so the tag still names exactly the audited tree.

[WRONG BRANCH] promote dev onto main for v2.34.0

[WRONG BRANCH] promote dev onto main for v2.35.0

Add .cursor/environment.json so Cloud Agents boot ready for the Bun-native runtime: install bun + project/gui dependencies, expose the proxy on port 8899, and run 'ocx start' as a persistent terminal. Co-authored-by: JUN <jun@lidgeai.com>

coderabbitai · 2026-08-28T16:10:58Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bfbbd310-58cd-4cfa-9944-720d681f9f15

📥 Commits

Reviewing files that changed from the base of the PR and between d7a82a8 and e4ef297.

📒 Files selected for processing (1)

AGENTS.md

📝 Walkthrough

Walkthrough

AGENTS.md adds guidance for Bun installation, proxy startup, endpoint access, and known environment-only test failures in minimal containers and agent sandboxes.

Changes

Minimal container documentation

Layer / File(s)	Summary
Container setup and test guidance `AGENTS.md`	Adds Bun installation instructions, the proxy startup command, `/healthz`, `/`, and management API access details, plus five known environment-only test failures and pass/skip/fail counts for version 2.35.0.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: ingwannu, wibias

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch cursor/setup-dev-environment-07c3

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-08-28T16:11:03Z

✅ Deterministic PR hygiene checks passed.

Drop the .cursor/environment.json added earlier on this branch and document the same knowledge as a 'Cursor Cloud specific instructions' section: Bun is not preinstalled (install via the official installer), how to run the proxy, and the five environment-only test failures (no systemd init; container filesystem mtime granularity) so future agents do not re-investigate them. Co-authored-by: JUN <jun@lidgeai.com>

Retitle the section 'Minimal containers and agent sandboxes' and phrase the guidance so it covers any fresh dev container or agent sandbox (Cursor Cloud, devcontainers, CI images): Bun is often absent, service tests need a running systemd init, and two integrity tests need fine mtime granularity. Co-authored-by: JUN <jun@lidgeai.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e4ef2972f9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-28T16:28:00Z

+- `package tree integrity > an in-place rewrite of the same byte length is
+  still a replacement` and `Codex Log Guard inspection > repeat inspection is
+  memoized and invalidated by a write` rely on filesystem mtime granularity
+  that some container filesystems do not provide.


Do not dismiss guard failures as container-only

On filesystems whose modification timestamp does not advance for these writes, the failures demonstrate real runtime behavior rather than harmless test flakiness: createPackageTreeIntegrityGuard cannot detect a same-size in-place package replacement, and the Codex log inspection cache can return stale metrics after a database write. Telling agents not to investigate these failures can therefore hide broken integrity and cache-invalidation guarantees; fix or explicitly disable the unsupported runtime behavior instead of treating the tests as known-safe failures.

AGENTS.md reference: AGENTS.md:L325-L327

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-28T16:28:00Z

+Run the proxy with `bun run src/cli/index.ts start --port <port>`. `/healthz`
+reports status, `/` serves the dashboard, and the management API requires the
+admin token the server writes to `$OPENCODEX_HOME/admin-api-token` at startup.


Document the default admin-token path

In the fresh-container scenario described here, OPENCODEX_HOME is normally unset, while getConfigDir() falls back to ~/.opencodex. An agent following this text literally will therefore look for /admin-api-token after shell expansion instead of the actual ~/.opencodex/admin-api-token and will be unable to authenticate direct management API requests. State both the default path and the environment-variable override.

Useful? React with 👍 / 👎.

…lidge-jun#2832) * release: v2.32.1 * release: v2.33.0 * chore: add Cloud Agent dev environment config Add .cursor/environment.json so Cloud Agents boot ready for the Bun-native runtime: install bun + project/gui dependencies, expose the proxy on port 8899, and run 'ocx start' as a persistent terminal. Co-authored-by: JUN <jun@lidgeai.com> * docs: record Cloud Agent setup in AGENTS.md instead of environment.json Drop the .cursor/environment.json added earlier on this branch and document the same knowledge as a 'Cursor Cloud specific instructions' section: Bun is not preinstalled (install via the official installer), how to run the proxy, and the five environment-only test failures (no systemd init; container filesystem mtime granularity) so future agents do not re-investigate them. Co-authored-by: JUN <jun@lidgeai.com> * docs: generalize sandbox setup notes beyond Cursor Cloud Retitle the section 'Minimal containers and agent sandboxes' and phrase the guidance so it covers any fresh dev container or agent sandbox (Cursor Cloud, devcontainers, CI images): Bun is often absent, service tests need a running systemd init, and two integrity tests need fine mtime granularity. Co-authored-by: JUN <jun@lidgeai.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com>

lidge-jun and others added 9 commits August 25, 2026 10:36

merge dev into main for the v2.32.1 release

d35592b

release: promote dev into main for v2.32.1

release: v2.32.1

71c57ea

merge dev into main for the v2.33.0 release

d560ac6

# Conflicts: # package.json

Merge pull request #2553 from lidge-jun/codex/promote-main-2330

08ada6f

[WRONG BRANCH] merge dev into main for the v2.33.0 release

release: v2.33.0

ec51e42

Merge pull request #2760 from lidge-jun/codex/promote-main-2340

80fff9a

[WRONG BRANCH] promote dev onto main for v2.34.0

Merge pull request #2826 from lidge-jun/codex/promote-main-2350

fc4de77

[WRONG BRANCH] promote dev onto main for v2.35.0

chore: add Cloud Agent dev environment config

68f5bbc

Add .cursor/environment.json so Cloud Agents boot ready for the Bun-native runtime: install bun + project/gui dependencies, expose the proxy on port 8899, and run 'ocx start' as a persistent terminal. Co-authored-by: JUN <jun@lidgeai.com>

github-actions Bot added the chore Maintenance, CI, tests, refactors, or build changes (not a user-facing bug or feature). label Aug 28, 2026

cursor Bot changed the title ~~chore: add Cloud Agent dev environment config~~ docs: add Cursor Cloud specific instructions to AGENTS.md Aug 28, 2026

github-actions Bot added documentation Improvements or additions to documentation and removed chore Maintenance, CI, tests, refactors, or build changes (not a user-facing bug or feature). labels Aug 28, 2026

cursor Bot changed the title ~~docs: add Cursor Cloud specific instructions to AGENTS.md~~ docs: add minimal container / agent sandbox instructions to AGENTS.md Aug 28, 2026

lidge-jun marked this pull request as ready for review August 28, 2026 16:24

lidge-jun requested a review from Ingwannu as a code owner August 28, 2026 16:24

lidge-jun merged commit 1a18ace into dev Aug 28, 2026
20 of 22 checks passed

lidge-jun deleted the cursor/setup-dev-environment-07c3 branch August 28, 2026 16:24

chatgpt-codex-connector Bot reviewed Aug 28, 2026

View reviewed changes

This was referenced Aug 28, 2026

Unable to compact v1 #2833

Closed

fix(kiro): render one answer when prose and the completion tool share an inference #2835

Merged

[Feature] Add relay model diagnostics for connectivity, latency, and identity consistency #2834

Open

Navigation Menu

docs: add minimal container / agent sandbox instructions to AGENTS.md - #2832

docs: add minimal container / agent sandbox instructions to AGENTS.md#2832
lidge-jun merged 11 commits into
devfrom
cursor/setup-dev-environment-07c3

lidge-jun commented Aug 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 28, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

github-actions Bot commented Aug 28, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Aug 28, 2026

Uh oh!

chatgpt-codex-connector Bot Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lidge-jun commented Aug 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

github-actions Bot commented Aug 28, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lidge-jun commented Aug 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 28, 2026 •

edited

Loading