remcodex 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -138,6 +138,12 @@ Before running this project, you should have:
 - Codex CLI installed and already working locally
 - A machine where this app can access your local Codex data and working directories
 
+On Linux, the first install may need a native build toolchain for `better-sqlite3` and `node-pty`:
+
+- `python3`
+- `make`
+- `g++`
+
 This project is currently developed primarily around a local macOS workflow.
 
 ## Quick Start
@@ -159,6 +165,84 @@ RemCodex starts a local server and opens the browser for you.
 
 If you want to make it reachable from your phone, expose the local machine on your LAN and open the same URL with your host IP.
 
+### Linux Install Note
+
+If `npx remcodex` appears to hang during the first install, it is usually still installing or compiling native dependencies.
+
+Make sure the machine has:
+
+- `python3`
+- `make`
+- `g++`
+
+Common setup examples:
+
+```bash
+# Debian / Ubuntu
+apt-get install -y python3 make g++
+
+# RHEL / CentOS / Rocky / Alibaba Cloud Linux
+yum install -y python3 make gcc-c++
+```
+
+## Install FAQ
+
+### Why does `npx remcodex` seem to hang on Linux?
+
+The package includes native dependencies such as `better-sqlite3` and `node-pty`.
+
+On some Linux machines, the first install may need to download or compile native binaries before RemCodex itself starts. That can look like a long spinner before you see any RemCodex output.
+
+### What usually fixes Linux install failures?
+
+Install the native build tools first:
+
+- `python3`
+- `make`
+- `g++`
+
+If you see `node-gyp`, `g++`, or build-related errors, the machine is usually missing part of that toolchain.
+
+### How can I get clearer logs than `npx remcodex`?
+
+If the first `npx` run is unclear, install it globally instead:
+
+```bash
+npm install -g remcodex
+remcodex doctor
+remcodex start
+```
+
+That usually makes native install errors much easier to read.
+
+### What if I am starting RemCodex on a headless server?
+
+Use:
+
+```bash
+npx remcodex --no-open
+```
+
+or:
+
+```bash
+remcodex start --no-open
+```
+
+RemCodex will still print the local and LAN URLs even when it does not try to open a browser.
+
+### Do I need Codex CLI installed first?
+
+Yes.
+
+RemCodex is a control surface for your local Codex runtime. If `codex` is not already installed and working in `PATH`, run:
+
+```bash
+remcodex doctor
+```
+
+and fix the reported Codex CLI issue first.
+
 ## Local CLI
 
 RemCodex also works well from source if you want to develop locally or inspect the runtime setup.

package/dist/server/src/app.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PORT = void 0;
 exports.resolvePackageRoot = resolvePackageRoot;
 exports.resolveDefaultDatabasePath = resolveDefaultDatabasePath;
 exports.startRemCodexServer = startRemCodexServer;
@@ -46,9 +47,10 @@ function resolvePackageRoot(startDir = __dirname) {
 function resolveDefaultDatabasePath() {
     return node_path_1.default.join((0, node_os_1.homedir)(), ".remcodex", "remcodex.db");
 }
+exports.DEFAULT_PORT = 18840;
 function buildRemCodexServer(options = {}) {
     const repoRoot = options.repoRoot ? node_path_1.default.resolve(options.repoRoot) : resolvePackageRoot();
-    const port = options.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? String(exports.DEFAULT_PORT), 10);
     const databasePath = options.databasePath ??
         process.env.DATABASE_PATH ??
         resolveDefaultDatabasePath();

package/dist/server/src/cli.js

@@ -169,7 +169,7 @@ async function runStart(flags) {
         printError("Install Codex first, or set CODEX_COMMAND to the correct executable.");
         return 1;
     }
-    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
+    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? String(app_1.DEFAULT_PORT), 10);
     const codexMode = process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server";
     let started = null;
     let activePort = preferredPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remcodex",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Control Codex from anywhere. Even on your phone.",
   "license": "MIT",
   "bin": {