remcodex 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -138,35 +138,122 @@ 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
 
-For the current developer preview, the recommended local install path is:
+For the current beta, the fastest way to try RemCodex is:
 
 ```bash
-npm install
-npm run build
-npm link
-remcodex start
+npx remcodex
 ```
 
-Then open:
+You can also install it globally:
 
-```text
-http://127.0.0.1:3000
+```bash
+npm install -g remcodex
+remcodex
 ```
 
+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 already ships with a local CLI entrypoint, even though the npm package is not published yet.
+RemCodex also works well from source if you want to develop locally or inspect the runtime setup.
 
-If you do not want to run `npm link`, you can call the built CLI directly:
+Local development path:
 
 ```bash
-node dist/server/src/cli.js start --no-open
+npm install
+npm run build
+npm link
+remcodex start
 ```
 
 Useful commands:
@@ -184,12 +271,6 @@ node dist/server/src/cli.js start --db ~/.remcodex/remcodex-alt.db --no-open
 node dist/server/src/cli.js doctor --db ~/.remcodex/remcodex-alt.db
 ```
 
-Planned install target after the npm package is published:
-
-```bash
-npx remcodex
-```
-
 ## Development
 
 ```bash
@@ -306,7 +387,7 @@ This is the honest list:
 - no production-grade auth / multi-user hardening yet
 - no release pipeline yet
 
-If you are comfortable cloning a repo and running a local Node app, you can use it today.
+If you are comfortable running a local Node app or a small CLI tool, you can use it today.
 
 ## Roadmap
 
@@ -320,12 +401,6 @@ Near-term:
 
 Later:
 
-- package for easier local install
+- improve the first-run install and update experience
 - optional sync / multi-device helpers
 - stronger sharing, auditing, and team workflows
-
-## License
-
-No license has been added yet.
-
-Until a license is added, assume this repository is **source-available for review only**, not open source for reuse.

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.1",
+  "version": "0.1.0-beta.3",
   "description": "Control Codex from anywhere. Even on your phone.",
   "license": "MIT",
   "bin": {