# LocalTerminal Lite

<p>
  <a href="https://github.com/wyj-IIRtyj/localterminal-lite/releases"><img src="https://img.shields.io/github/v/release/wyj-IIRtyj/localterminal-lite?style=flat-square&logo=github" alt="Latest release" /></a>
  <a href="https://github.com/wyj-IIRtyj/localterminal-lite/stargazers"><img src="https://img.shields.io/github/stars/wyj-IIRtyj/localterminal-lite?style=flat-square&logo=github" alt="GitHub stars" /></a>
  <a href="https://github.com/wyj-IIRtyj/localterminal-lite/blob/main/LICENSE"><img src="https://img.shields.io/github/license/wyj-IIRtyj/localterminal-lite?style=flat-square" alt="License" /></a>
  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
  <img src="https://img.shields.io/badge/MCP-enabled-7C3AED?style=flat-square" alt="MCP enabled" />
</p>

> **Tech stack:** Bun · TypeScript · React 19 · OpenTUI · MCP · OpenAPI 3.1 · Express  
> **Language:** **English** · [中文](README.zh-CN.md)

LocalTerminal Lite lets ChatGPT work inside one local project through an auditable terminal control plane. It supports either **ChatGPT Apps/Plugins (MCP)** or **custom GPT Actions**.

## Start here

Follow these four steps in order. You do not need Git, Node.js, Bun, or another programming environment.

### 1. Install LocalTerminal Lite

Choose your platform. The installer downloads the matching standalone `v1.1.2` binary, verifies SHA-256, registers the `localterminal-lite` command, and starts the TUI.

#### macOS

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/wyj-IIRtyj/localterminal-lite/v1.1.2/scripts/install-macos.sh)"
```

#### Linux

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/wyj-IIRtyj/localterminal-lite/v1.1.2/scripts/install-linux.sh)"
```

#### Windows PowerShell

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/wyj-IIRtyj/localterminal-lite/v1.1.2/scripts/install-windows.ps1 | iex"
```

> [!IMPORTANT]
> **Known Windows limitation:** the supported PowerShell TUI path is keyboard-only compatibility mode. Mouse capture is disabled by default because it can become unresponsive or freeze in Windows PowerShell and PowerShell 7. Every page remains keyboard-operable. `LITE_WINDOWS_TUI_MODE=mouse` is experimental and should not be used for critical work.

For offline assets, checksum inspection, or release candidates, use the [manual installation guide](docs/MANUAL_INSTALL.md).

### 2. Install Cloudflare Tunnel

ChatGPT cannot connect directly to `127.0.0.1`. Install Cloudflare's `cloudflared` for your platform.

#### macOS

With Homebrew:

```bash
brew install cloudflared
cloudflared --version
```

Without Homebrew:

```bash
CF_ARCH="$(uname -m)"
[ "$CF_ARCH" = "arm64" ] && CF_ARCH="arm64" || CF_ARCH="amd64"
curl -fsSL "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-darwin-${CF_ARCH}.tgz" -o /tmp/cloudflared.tgz
tar -xzf /tmp/cloudflared.tgz -C /tmp
sudo install /tmp/cloudflared /usr/local/bin/cloudflared
cloudflared --version
```

#### Debian or Ubuntu Linux

```bash
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update
sudo apt-get install cloudflared
cloudflared --version
```

For other Linux distributions, use Cloudflare's [official downloads page](https://developers.cloudflare.com/tunnel/downloads/).

#### Windows PowerShell

```powershell
$CloudflaredDir = Join-Path $env:LOCALAPPDATA "cloudflared"
New-Item -ItemType Directory -Force $CloudflaredDir | Out-Null
Invoke-WebRequest "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe" -OutFile (Join-Path $CloudflaredDir "cloudflared.exe")
& (Join-Path $CloudflaredDir "cloudflared.exe") --version
```

### 3. Start Lite and the HTTPS tunnel

Start Lite in one terminal:

```text
localterminal-lite
```

Complete the first-run TUI setup. Keep the default local port unless you have a reason to change it.

Start a development Quick Tunnel in a second terminal:

```bash
cloudflared tunnel --url http://127.0.0.1:3210
```

Windows, if `cloudflared` is not on `PATH`:

```powershell
& "$env:LOCALAPPDATA\cloudflared\cloudflared.exe" tunnel --url http://127.0.0.1:3210
```

Copy the generated `https://...trycloudflare.com` address. In Lite, open **6 Settings**, press `c`, and set **Public HTTPS URL** to that address. Quick Tunnels are intended for development/testing and receive a new random URL after restart; use a named tunnel and stable hostname for long-lived use.

### 4. Choose one ChatGPT connection

Choose exactly one path:

| Connection | Best for | Continue with |
| --- | --- | --- |
| **ChatGPT Apps/Plugins (MCP)** | A ChatGPT plan/workspace that can create a custom MCP app or connector. Apps gets direct tools plus the complete generic extension facade. | [Apps/Plugins setup](docs/APPS_SETUP.md) |
| **Custom GPT Actions** | A custom GPT configured with LocalTerminal's three-operation OpenAPI Action. | [Actions setup](docs/ACTIONS_SETUP.md) |

Do not attach both connection types to the same GPT.

## What you get

- One read/write workspace by default, plus individually configured read-only or read/write additional roots when needed.
- Auditable root and child sessions, durable checkpoints, continuation history, events, and messages.
- A seven-page TUI for Overview, Sessions, Messages, Diff, Extensions, Settings, and Logs.
- Optional enhanced Actions long-task enforcement and optional non-blocking task scheduling; both are independent and off by default.
- Apps retains arbitrary commands, overwriting writes, patches, and custom extensions through the generic facade while also exposing smaller direct MCP tools.

## Documentation

### User guides

- [Apps/Plugins setup](docs/APPS_SETUP.md)
- [Custom GPT Actions setup](docs/ACTIONS_SETUP.md)
- [Recommended custom GPT instructions](docs/GPT_INSTRUCTIONS.md)
- [Short prompt playbook](docs/PROMPT_PLAYBOOK.md)
- [Manual/offline installation](docs/MANUAL_INSTALL.md)
- [Privacy and deployment template](docs/PRIVACY.md)

### Maintainers

- [Architecture and ownership](docs/architecture.md)
- [Security policy](SECURITY.md)
- [Release notes](RELEASE_NOTES.md)

## Build from source

Requirements: Bun 1.3 or newer.

```bash
git clone https://github.com/wyj-IIRtyj/localterminal-lite.git
cd localterminal-lite
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run dev
```

Headless mode is available after first-run TUI setup:

```bash
bun run build
bun run start -- --headless
```

## Security and privacy

The selected workspace is read/write. Additional directories remain unavailable until each is added under **Settings → authorized-roots** with read or write access. Use a dedicated project, review Diff and Logs, keep credentials masked, and stop public tunnels when they are not needed. Lite has no project telemetry. Read the [privacy notice](docs/PRIVACY.md) and report vulnerabilities through [SECURITY.md](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE). LocalTerminal Lite is an independent open-source project and is not affiliated with or endorsed by OpenAI or Cloudflare.