docs: add Cursor Cloud dev environment setup notes to AGENTS.md - #103
Conversation
Co-authored-by: Jared Wray <me@jaredwray.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #103 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 8 8
Lines 1399 1399
Branches 303 303
=========================================
Hits 1399 1399 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fddc21eac1
ℹ️ 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".
| - `sudo chmod 666 /var/run/docker.sock` | ||
| - Then `pnpm test:services:start` (docker compose) brings up memcached on ports `11211`, `11212`, `11213` and a SASL server on `11215`. `pnpm test` / `pnpm test:ci` need these running or most suites fail. | ||
| - Docker note: the daemon is configured with the `fuse-overlayfs` storage driver and `containerd-snapshotter` disabled (required for Docker 29 in this VM). This is already set in `/etc/docker/daemon.json`. | ||
| - Known environment-only test failures: the two `should handle connection timeout` tests (`test/index.test.ts`, `test/node.test.ts`) fail here because outbound TCP to the reserved TEST-NET-1 address `192.0.2.0` connects instantly in this sandbox instead of timing out. This is a network-environment quirk, not a code bug; these pass on GitHub CI. All other tests (610) pass. |
There was a problem hiding this comment.
On Cursor Cloud, this note normalizes a 610/612 result even though the repository's mandatory gate requires pnpm test to succeed with 100% coverage. Future agents following these instructions can therefore commit changes with a red suite and potentially misclassify a real timeout regression as the documented environment quirk; the environment-specific failures should be resolved or handled deterministically rather than treated as acceptable.
AGENTS.md reference: AGENTS.md:L7-L8
Useful? React with 👍 / 👎.
| - `sudo dockerd > /tmp/dockerd.log 2>&1 &` | ||
| - `sudo chmod 666 /var/run/docker.sock` |
There was a problem hiding this comment.
On a fresh VM where /var/run/docker.sock does not exist, backgrounding dockerd returns control before the daemon has necessarily created the socket, so the immediately following chmod can fail with ENOENT. Because the socket is then created with its default restricted permissions, the non-sudo pnpm test:services:start step can still be unable to connect; wait until the socket exists before changing its permissions.
Useful? React with 👍 / 👎.
| - Node version: the repo requires Node `>=22.19.0`. The system node at `/exec-daemon/node` is too old; `~/.bashrc` is configured to prioritize nvm's default Node 24 and `pnpm` comes from corepack. Login shells (the default) already resolve the correct `node`/`pnpm`, so no manual `nvm use` is needed. | ||
| - Docker is required for tests but the daemon does NOT auto-start. Before running integration tests, start it once per session and make the socket usable by the repo's non-sudo scripts: | ||
| - `sudo dockerd > /tmp/dockerd.log 2>&1 &` | ||
| - `sudo chmod 666 /var/run/docker.sock` |
There was a problem hiding this comment.
When the Cursor VM contains another unprivileged user or service, changing the Docker socket to mode 0666 lets that account control the root-owned daemon, including launching privileged containers or mounting host files, which effectively provides host root access. Grant access only to the intended agent user or a restricted group instead of giving every local account write access.
Useful? React with 👍 / 👎.
2 participants
Please check if the PR fulfills these requirements
What kind of change does this PR introduce?
Docs update. This adds a
## Cursor Cloud specific instructionssection toAGENTS.mddocumenting how to set up and run the development environment in a Cursor Cloud agent VM. No source code is changed.Notes captured for future agents:
>=22.19.0is required; the system/exec-daemon/nodeis too old, so~/.bashrcprioritizes nvm's Node 24 (pnpm via corepack).sudo dockerd &,chmod 666the socket), thenpnpm test:services:startbrings up memcached on11211-11213plus SASL on11215.fuse-overlayfsstorage driver withcontainerd-snapshotterdisabled.should handle connection timeouttests fail only in this sandbox because outbound TCP to reserved192.0.2.0connects instantly instead of timing out; they pass on GitHub CI. All other 610 tests pass.Verification
pnpm build— succeeds (ESM + CJS + type declarations)pnpm lint— clean (Biome)pnpm test— 610/612 pass (2 env-only network-timeout failures described above)connect→set→get→incr→deleteall succeed.