Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix(dev): keep tmux sockets under ~/.openhands so macOS won't reap them (#1107)

Xingyao Wang9e8b068850be
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index 0153647160..a6a6e530df 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -591,9 +591,7 @@ describe("buildSafeDevConfig", () => {
expect(config.stateDir).toBe(
path.join(homedir(), ".openhands", "agent-canvas"),
);
- expect(config.tmuxTmpDir).toBe(
- path.join(tmpdir(), "openhands-agent-canvas-tmux"),
- );
+ expect(config.tmuxTmpDir).toBe(path.join(config.stateDir, "tmux"));
expect(config.conversationsPath).toBe(
path.join(config.stateDir, "dev_conversations"),
);
@@ -622,6 +620,17 @@ describe("buildSafeDevConfig", () => {
expect(config.backendHost).toBe("127.0.0.1:19000");
expect(config.stateDir).toBe(path.resolve(cwd, ".tmp", "dev-safe"));
expect(config.workingDir).toBe("/workspace/custom-repo");
+ // tmux socket dir defaults to <stateDir>/tmux.
+ expect(config.tmuxTmpDir).toBe(path.join(config.stateDir, "tmux"));
+ });
+
+ it("honors TMUX_TMPDIR for hosts without socket-capable homes", () => {
+ const config = buildSafeDevConfig("/workspace/project/agent-canvas", {
+ TMUX_TMPDIR: "/tmp",
+ OH_SESSION_API_KEY_PATH: tempKeyPath(),
+ });
+
+ expect(config.tmuxTmpDir).toBe("/tmp");
});
it("falls back to the persisted session key file when no env override is set", () => {
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 7f60c0c43b..321a14935c 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -27,9 +27,12 @@ The dev stack uses `uvx` to run a temporary `agent-server`
installation on `127.0.0.1:18000` and points the frontend at it. It isolates
conversation persistence by setting separate `OH_CONVERSATIONS_PATH`,
`OH_BASH_EVENTS_DIR`, and `OH_VSCODE_PORT` values under `.openhands-dev/`, and
-places tmux sockets under `/tmp` (via `TMUX_TMPDIR`) to avoid filesystem-support
-issues, so it does not collide with other local or cloud-backed OpenHands
-sessions.
+keeps its tmux sockets under `~/.openhands/agent-canvas/tmux` (via
+`TMUX_TMPDIR`), so it does not collide with other local or cloud-backed
+OpenHands sessions. If `$HOME` is on a filesystem that does not support Unix
+domain sockets (some devcontainers, NFS/CIFS homes), set the standard
+`TMUX_TMPDIR` env var to a local path such as `/tmp` and the dev stack will use
+it instead.
### Environment Variables
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index af9b117688..ac3a83da40 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -10,7 +10,7 @@ import {
writeFileSync,
} from "node:fs";
import net from "node:net";
-import { homedir, tmpdir } from "node:os";
+import { homedir } from "node:os";
import path from "node:path";
import process from "node:process";
import { setTimeout as delay } from "node:timers/promises";
@@ -622,7 +622,23 @@ function buildConfigFromPorts(ports, cwd, env) {
backendPort,
vscodePort,
stateDir,
- tmuxTmpDir: path.join(tmpdir(), "openhands-agent-canvas-tmux"),
+ // tmux socket directory. Defaults to <stateDir>/tmux (under
+ // ~/.openhands/agent-canvas), matching where the rest of dev state lives
+ // and persisting across restarts.
+ //
+ // Do NOT use os.tmpdir() here: on macOS it resolves to the per-user
+ // $TMPDIR (/var/folders/.../T), which the OS periodically reaps
+ // (com.apple.bsd.dirhelper deletes entries untouched for a few days).
+ // Reaping deletes the live tmux socket while the server process keeps
+ // running, orphaning it β€” every later new-window then fails with
+ // "error connecting to .../openhands (No such file or directory)".
+ //
+ // The only hosts where <stateDir>/tmux can't hold the socket are those
+ // whose $HOME is a network/overlay mount without Unix-domain-socket
+ // support (some devcontainers, NFS/CIFS homes). Those rare cases can point
+ // tmux at a local, socket-capable path with the standard TMUX_TMPDIR env
+ // var (e.g. TMUX_TMPDIR=/tmp), which we honor and pass through below.
+ tmuxTmpDir: env.TMUX_TMPDIR || path.join(stateDir, "tmux"),
conversationsPath,
workspacesPath,
bashEventsDir: path.join(stateDir, "bash_events"),