Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(dev-docker): allow exec on the home tmpfs so stdio MCP servers work (#535)

Tim O'Farrell0cf58f865728
diff --git a/__tests__/scripts/dev-docker.test.ts b/__tests__/scripts/dev-docker.test.ts
index 94e4bf7d0b..fe7a8270a9 100644
--- a/__tests__/scripts/dev-docker.test.ts
+++ b/__tests__/scripts/dev-docker.test.ts
@@ -51,10 +51,15 @@ describe("docker host user", () => {
expect(getDockerUserArgs(null)).toEqual([]);
});
- it("mounts a writable tmpfs home for the mapped host user", () => {
+ it("mounts a writable, executable tmpfs home for the mapped host user", () => {
+ // `exec` is critical: docker's --tmpfs default is rw,noexec,nosuid,nodev,
+ // which breaks stdio MCP servers that exec binaries cached under ~/.npm
+ // (e.g. `npx -y @modelcontextprotocol/server-github`). We keep `nosuid`
+ // and `nodev` as defense-in-depth -- $HOME has no business hosting
+ // setuid binaries or device nodes -- but the `noexec` default has to go.
expect(getDockerHomeTmpfsArgs("1000:1000")).toEqual([
"--tmpfs",
- "/home/openhands:uid=1000,gid=1000,mode=700",
+ "/home/openhands:exec,nosuid,nodev,uid=1000,gid=1000,mode=700",
]);
expect(getDockerHomeTmpfsArgs(null)).toEqual([]);
});
diff --git a/scripts/dev-docker.mjs b/scripts/dev-docker.mjs
index 7a3aa1be43..306c18c67c 100644
--- a/scripts/dev-docker.mjs
+++ b/scripts/dev-docker.mjs
@@ -193,6 +193,18 @@ function getDockerUserArgs(userSpec = getHostDockerUserSpec()) {
* Cache/config writes that libraries place under $HOME stay ephemeral in this
* tmpfs. The only persisted default-home state is the explicit
* ~/.openhands -> /home/openhands/.openhands bind mount below.
+ *
+ * We explicitly pass `exec` because docker's `--tmpfs` default option set is
+ * `rw,noexec,nosuid,nodev`. `noexec` breaks any agent flow that needs to run a
+ * binary out of `$HOME` -- most visibly stdio MCP servers installed via
+ * `npx -y @modelcontextprotocol/server-*`, which cache their executables under
+ * `~/.npm/_npx/...` and then exec them. With the default `noexec` flag, those
+ * execs fail with "Permission denied" regardless of the file mode bits, and
+ * the failure only surfaces when a conversation tries to spin the MCP server
+ * up -- aborting agent initialization with a confusing traceback.
+ *
+ * `nosuid` and `nodev` are preserved (the home dir has no business hosting
+ * setuid binaries or device nodes); only the `noexec` default is overridden.
*/
function getDockerHomeTmpfsArgs(userSpec = getHostDockerUserSpec()) {
if (!userSpec) {
@@ -204,7 +216,10 @@ function getDockerHomeTmpfsArgs(userSpec = getHostDockerUserSpec()) {
return [];
}
- return ["--tmpfs", `${CONTAINER_HOME_DIR}:uid=${uid},gid=${gid},mode=700`];
+ return [
+ "--tmpfs",
+ `${CONTAINER_HOME_DIR}:exec,nosuid,nodev,uid=${uid},gid=${gid},mode=700`,
+ ];
}
/**