terminal-commands 0.1.1

package/README.md

@@ -0,0 +1,130 @@
+# Terminal Commands companion
+
+A self-hosted MCP server for controlled terminal and filesystem access on the machine where it runs, reachable from ChatGPT, Claude, or any MCP-compatible client — locally over stdio, or remotely from ChatGPT web through Secure MCP Tunnel.
+
+It can also run as the local execution component for the hosted Terminal Commands gateway. The
+gateway connection is outbound-only and works on Windows, macOS, and Linux. The headless companion
+forwards read-only tools by default and refuses command execution and file writes until terminal
+approval prompts are enabled.
+
+## Security model
+
+- Binds to `127.0.0.1` by default and refuses public interfaces unless explicitly enabled.
+- Intended for OpenAI Secure MCP Tunnel during private development.
+- Marks command execution and file writes as destructive and also requires approval in the companion terminal.
+- Runs programs without a shell. Shells, `sudo`, and `su` are blocked by default.
+- Passes only a small environment allowlist to child processes, excluding API keys and other secrets.
+- Restricts dedicated filesystem tools to the approved roots.
+
+Command-line programs still execute with your operating-system user permissions. A program can access more than the dedicated filesystem tools, so review every command approval carefully.
+
+## Run
+
+```bash
+npm install
+npm run build
+MACHINE_TERMINAL_ROOTS="$HOME" npm start
+```
+
+The health endpoint is `http://127.0.0.1:3333/health` and MCP is available at `http://127.0.0.1:3333/mcp`.
+
+## Command line
+
+```bash
+terminal-commands login
+terminal-commands connect --root ~/Documents/GitHub --root ~/work
+```
+
+From a checkout, the same commands run through npm. Everything after `--` reaches the CLI:
+
+```bash
+npm run cli -- connect --root ~/Documents/GitHub --allow-destructive
+npm run cli -- connect --help
+```
+
+Commands: `login`, `connect`, `status`, `logout`, `help`. Add `--help` to any of them to see only
+the options it accepts.
+
+### Options
+
+| Option                     | Applies to      | Environment variable                       | Meaning                                                                                                                           |
+| -------------------------- | --------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `-r, --root <path>`        | connect, status | `MACHINE_TERMINAL_ROOTS`                   | Approved filesystem root. Repeat the flag, or separate paths with the platform path delimiter. Defaults to the current directory. |
+| `--name <name>`            | connect, status | `MACHINE_TERMINAL_DEVICE_NAME`             | Device name shown in the client. Defaults to the hostname.                                                                        |
+| `--device-id <id>`         | connect, status | `MACHINE_TERMINAL_DEVICE_ID`               | Device identifier to report. Defaults to the saved local device ID.                                                               |
+| `--port <port>`            | connect, status | `MACHINE_TERMINAL_PORT`                    | Port for the local MCP service. Defaults to `3333`.                                                                               |
+| `--host <host>`            | connect, status | `MACHINE_TERMINAL_HOST`                    | Bind address for the local MCP service. Defaults to `127.0.0.1`.                                                                  |
+| `--gateway-url <url>`      | connect, status | `MACHINE_TERMINAL_GATEWAY_URL`             | Gateway WebSocket URL.                                                                                                            |
+| `--allow-destructive`      | connect         | `MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE` | Ask in the terminal before each command and file write. Without it both are refused.                                              |
+| `--auto-approve`           | connect         | `MACHINE_TERMINAL_AUTO_APPROVE`            | Approve every command and file write automatically, without a terminal prompt. Implies `--allow-destructive`. Use with caution.   |
+| `--allow-shell`            | connect         | `MACHINE_TERMINAL_ALLOW_SHELL`             | Permit shells and privilege tools such as `sudo`.                                                                                 |
+| `--allowed-program <name>` | connect         | `MACHINE_TERMINAL_ALLOWED_PROGRAMS`        | Executable allowlist. Repeat the flag or separate names with commas.                                                              |
+| `--allow-public-bind`      | connect         | `MACHINE_TERMINAL_ALLOW_PUBLIC_BIND`       | Permit a non-loopback bind. Only behind authenticated HTTPS.                                                                      |
+| `--auth-issuer <url>`      | all             | `MACHINE_TERMINAL_AUTH_ISSUER`             | OAuth issuer, for a self-hosted gateway.                                                                                          |
+| `--auth-client-id <id>`    | all             | `MACHINE_TERMINAL_AUTH_CLIENT_ID`          | OAuth client ID.                                                                                                                  |
+| `--auth-audience <url>`    | all             | `MACHINE_TERMINAL_AUTH_AUDIENCE`           | OAuth audience.                                                                                                                   |
+| `--dry-run`                | connect         | —                                          | Print the resolved settings and exit without starting anything.                                                                   |
+| `--json`                   | connect, status | —                                          | Print machine-readable JSON.                                                                                                      |
+
+A flag beats the environment variable, and the environment beats the default. `--root` replaces
+`MACHINE_TERMINAL_ROOTS` rather than adding to it. On/off options accept `--no-` forms, so
+`--no-allow-shell` overrides an environment variable that enabled shells.
+
+Roots are expanded (`~` included), resolved to absolute paths, de-duplicated, and checked before
+anything starts, so a typo fails immediately instead of silently approving the wrong folder.
+`connect --dry-run` prints exactly what would be approved:
+
+```bash
+npm run cli -- connect --root ~/Documents/GitHub --dry-run
+```
+
+## Configuration
+
+Every option above can be set through its environment variable instead, which is what the Codex
+plugin and service managers do.
+
+- `MACHINE_TERMINAL_ROOTS`: path-delimited filesystem roots. Defaults to the directory where the companion starts.
+- `MACHINE_TERMINAL_HOST`: bind host. Defaults to `127.0.0.1`.
+- `MACHINE_TERMINAL_PORT`: bind port. Defaults to `3333`.
+- `MACHINE_TERMINAL_ALLOWED_PROGRAMS`: optional comma-delimited executable allowlist.
+- `MACHINE_TERMINAL_ALLOW_SHELL=1`: permits shells and privilege tools. Avoid enabling this unless necessary.
+- `MACHINE_TERMINAL_ALLOW_PUBLIC_BIND=1`: permits a non-loopback bind. Do not enable without authenticated HTTPS and OAuth 2.1.
+- `MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE=1`: enables a terminal prompt for every command or file write. Non-interactive sessions deny these actions.
+- `MACHINE_TERMINAL_AUTO_APPROVE=1`: approves every command and file write automatically, without prompting. Implies `MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE=1`. Use with caution, and only when you trust the connected client.
+
+## Hosted gateway companion
+
+Run the local HTTP server and companion as separate processes:
+
+```bash
+npm start
+MACHINE_TERMINAL_GATEWAY_URL="wss://mcp.terminalcommands.fr/device/connect" \
+MACHINE_TERMINAL_DEVICE_TOKEN="<short-lived-device-token>" \
+MACHINE_TERMINAL_DEVICE_ID="my-computer" \
+npm run start:agent
+```
+
+The `terminal-commands login` command obtains the device token through OAuth Device Authorization
+and stores it in a private local configuration file. Do not put real tokens in shell history.
+
+## Connect an MCP client
+
+Any MCP-compatible client can use this server. Local, stdio-based clients (such as Codex) connect
+directly to the process; remote clients connect over HTTP to `http://127.0.0.1:3333/mcp` through a
+tunnel or the hosted gateway.
+
+### Connect ChatGPT web
+
+1. Start this server locally.
+2. In ChatGPT, enable Developer mode under **Settings → Security and login**.
+3. Create or start an OpenAI Secure MCP Tunnel targeting `http://127.0.0.1:3333/mcp`.
+4. In the Plugins page, add a connection, choose **Tunnel**, and select its `tunnel_id`.
+5. Review the discovered tools and test in a new conversation.
+
+### Connect Claude or other MCP clients
+
+Point the client's remote MCP server configuration at the same `http://127.0.0.1:3333/mcp` endpoint
+(or the tunneled/hosted HTTPS URL, once configured). Refer to the client's own documentation for how
+it registers remote MCP servers; the connection and tool-discovery steps are otherwise identical.
+
+For a published or independently hosted server, deploy a stable public HTTPS `/mcp` endpoint and implement OAuth 2.1. Do not expose this local server directly to the internet.