# Vimoora Terminal

Version **1.4.0** adds a top-bar Codex updater and project removal/reopening.
Codex runs independently in each project to prevent shared background-server
version and feature conflicts. Project switching preserves drafts without an
unnecessary “Leave site” alert.
Unsaved editor changes still have their own protection. Includes independent
project sessions, draft recovery, adjustable panels, light/dark themes,
fullscreen and compact touch controls.

Install the Vimoora browser development terminal on your own server. This uses the
same ttyd 1.7.7 terminal, compact toolbar, file browser, uploads, clipboard
fallbacks, touch scrolling and tmux/Codex scrolling fixes as the Vimoora studio.
Text uses the DOM renderer to keep high-DPI phone output correctly sized without
depending on GPU rendering.
The surrounding studio shell has its own login; the Vimoora game admin/backend is
not part of this package. No server keys, passwords, ChatGPT sessions, or projects
are copied from Vimoora.

## Install with HTTPS

Use Ubuntu 22.04+ or Debian 12+, x86_64/ARM64, with systemd and root/sudo access.
Point a hostname to the server and allow inbound TCP 80 and 443. Those ports must
be free for the installer's Caddy service.

```bash
curl -fsSL https://downloads.vimoora.io/terminal/install.sh | sudo bash -s -- --domain terminal.example.com
```

Replace `terminal.example.com` with your hostname. SSL does not need to exist first:
the installer obtains a certificate automatically once DNS and ports are ready.

After installation, open the **private setup link** printed by the installer. On
your subdomain, choose your username, enter your own password (12+ characters), and
confirm it. Selecting **Create account** signs you in and opens the terminal.

The terminal stays locked until setup is complete. The setup link works once and
expires after 24 hours. Its secret is kept in the URL fragment, removed from browser
history on opening, and never included in HTTP/access-log URLs. The link is also
saved root-only at `/etc/vimoora-terminal/setup-link`. If you open the subdomain
without the private link, the setup page asks for the setup code; a random visitor
cannot create the account. To replace a lost/expired link before setup:

```bash
sudo vimoora-terminal setup
```

After setup, the subdomain shows the normal sign-in page and setup cannot be reused.
An update preserves existing accounts, including accounts installed with version
1.0.0. For automated provisioning, `--password-file /root/terminal-password` still
sets a password during installation and skips browser setup.

In the terminal run:

```bash
codex login --device-auth
codex
```

Authorize Codex with your own account. The terminal uses the tested Codex **0.157.0**
release, matching the original studio; it does not silently install a different CLI.
Node 24.21.0, ttyd 1.7.7 and Caddy 2.11.7 are checksum pinned for both architectures.
Future installer releases can update those pins after compatibility testing.

The **Codex update** button beside the theme/fullscreen controls checks the
official stable release channel. When its update dot appears, click once to
download, verify and activate the new CLI for all projects. Progress continues
on the server if you close the browser. Running Codex sessions keep their current
version; exit and resume them when convenient. Failed verification leaves the
previous version active. Reinstalling this terminal preserves a newer CLI already
installed through the button. Update access requires the terminal's owner login.

The web terminal's `codex` command disables automatic shared-daemon use. Each
project runs its own Codex process inside tmux, so closing the browser still
leaves work running. Login and saved conversation history stay in your Codex home.
Existing shared Codex servers are not restarted or stopped. After updating an
older installation, run `source /opt/vimoora-terminal/current/app/bashrc` at an
idle shell prompt to update that already-open shell; new project shells use the
new launcher automatically. To bypass a shared-server conflict prompt in an old
shell immediately, choose **Run without daemon this time**.

## Built-in editor

The project bar starts with **Current session**, preserving the existing shell.
Choose **+ Open project**, give it a name and select an existing folder inside
Projects. Each project gets its own persistent terminal, working directory and
editor workspace. Up to 24 additional projects are supported. Switching projects
or closing the browser disconnects the view; commands keep running on the server.
Returning in the same browser restores the last project and reconnects its shell.
You can open the project URL in another browser tab when you need simultaneous views.
Create new project folders through the terminal before opening them in the project bar.
Use **×** beside a project tab to remove it from the list. Its files, drafts and
running terminal remain intact. Open the same folder again to restore the same
session. **Current session** stays available. Removing a tab does not stop a job;
stop commands in that terminal when you want them to end.

Choose **Editor** to browse your workspace, or **Split** on desktop to keep code
and the live terminal side by side. On phones, use the **Terminal / Editor** buttons
at the bottom. Switching views keeps the same terminal connection and running CLI.
The terminal's **Files** panel also has **Edit** for supported files.

- Drag the divider between Editor and Terminal, or beside the file explorer, to
  resize panels. You can also focus a divider and use Left/Right (Shift for larger
  steps), Home/End, or double-click to reset. Sizes are remembered in this browser.
- Use the sun/moon button to switch between **Light** and **Dark**. The editor,
  terminal palette, controls and dialogs follow the theme, which is remembered.
  CLI programs can still draw their own explicit colors.
- Use **Fullscreen** beside the theme button to fill the screen. Exit with the
  same button or Escape. Browsers without native fullscreen expand the workspace
  inside the browser window. Views and the terminal session stay connected.
- Desktop shows Paste, Attach, New line, Copy and Files. Touch devices also show
  **Left/Right** to move the terminal cursor, **Up/Down** to scroll the conversation,
  and **Latest** to return to the prompt. The compact toolbar scrolls horizontally
  on narrow screens. Cursor buttons preserve an already-open phone keyboard.

- Open up to eight files in tabs. Unsaved drafts and undo history stay in their tabs.
- Use **Save** or Ctrl/Cmd+S; search/replace, undo/redo, syntax highlighting,
  language completion and code folding are included.
- Saved changes write to the same server files your CLI uses. Saving source does
  not automatically build, deploy, or restart your application.
- When Codex or another tool changes a file, clean tabs update from disk. Unsaved
  tabs show a comparison before saving. **Keep my draft** lets you review and save
  deliberately; **Use disk version** replaces the draft. A further disk change
  triggers another conflict. You can download a draft from the comparison.
- Open files, cursor position, view and unsaved drafts are recovered per project
  and account in the same browser using IndexedDB. Recovery never writes source
  files automatically: use **Save** to do that. If a file changed while you were
  away, the recovered draft is compared before saving. Switching projects waits
  for draft storage to finish. Refresh, tab closing and sign-out still warn about
  unsaved edits. Recovery requires browser storage; clearing site data removes it,
  and it does not transfer drafts to another device. Save important edits normally.

The editor supports UTF-8 text up to 1 MiB, preserves LF/CRLF line endings and file
permissions, and saves through a temporary file followed by an atomic rename.
Hidden paths, symbolic links and dependency folders are excluded, matching the file
browser. Read-only and hardlinked files cannot be saved in the editor. Use the CLI
for those files, binary files, larger files, or files outside the configured workspace.
Project deletion is still unavailable in the file browser.

CodeMirror and its language support are bundled locally; the editor does not load
scripts from a public CDN. It has Vimoora's interface, not the VS Code extension
system. Bundled license notices are available at
`/admin/dev/terminal/editor-licenses.txt` after signing in.

By default, installation creates a dedicated `codex` Linux account without sudo,
and `~/projects` as the workspace. To use your existing development account:

```bash
curl -fsSL https://downloads.vimoora.io/terminal/install.sh | sudo bash -s -- \
  --domain terminal.example.com --user deploy --workspace /srv/projects
```

The terminal has that account's existing file permissions and privileges. Existing
project ownership is never changed recursively. This is one trusted user's server
shell, not a multi-user hosting service.

## Existing reverse proxy

Use `--origin https://terminal.example.com` instead of `--domain`. The installer
binds only to `127.0.0.1:7680` and writes a Caddy example to
`/etc/vimoora-terminal/proxy-example.Caddyfile`. Configure your own proxy to preserve
the original Host, support WebSocket upgrades, and allow uploads up to 25 MB.
Do not expose the loopback port directly. The ttyd backend uses a private Unix
socket; it is not exposed on any TCP port.

## Without a domain

```bash
curl -fsSL https://downloads.vimoora.io/terminal/install.sh | sudo bash
ssh -L 7680:127.0.0.1:7680 YOUR_SSH_USER@YOUR_SERVER
```

Open the printed localhost setup link after creating the SSH tunnel; after setup,
use `http://127.0.0.1:7680/admin/dev`.
For direct Android/browser access use the HTTPS hostname option.

## Updates and management

Re-run the installer with the same options, or with no options on an existing
installation. It preserves the endpoint, workspace, browser password, uploads,
exports and Codex login. Web/TTY services restart and the browser reconnects to the
existing tmux shell. Rebooting the server starts a new shell; running processes do
not survive a reboot. Installs do not overwrite the account's `.bashrc` or Codex
configuration. The installed runtimes are available inside the browser shell and
under `/opt/vimoora-terminal/tools`.

```bash
sudo vimoora-terminal status
sudo vimoora-terminal restart
sudo vimoora-terminal setup
sudo vimoora-terminal password
sudo journalctl -u vimoora-terminal-web -u vimoora-terminal-tty -n 100
sudo vimoora-terminal uninstall
```

`restart` preserves the shell. `setup` rotates the private setup link only while
initial setup is incomplete. `password` prompts privately and revokes browser
sessions. `uninstall` stops/disables/removes the terminal services, ending the shell;
it deliberately retains projects, accounts, configuration, runtimes and uploaded
files so you can recover/reinstall them. Review and delete those retained directories
manually if you want to remove all data.

Uploads/exports live in `/var/lib/vimoora-terminal/{uploads,exports}`. Project files
can be browsed/downloaded from the Files button; deletion in that UI is restricted
to uploads and exports. Login cookies last 30 days; Sign out revokes the current
cookie and its terminal connections within 30 seconds. Refreshing or signing out
does not stop processes in the persistent shell.

Use `--username`, `--password-file`, or `--port` during initial provisioning to
override defaults. `--no-start` installs/enables units without starting them, for
image building. Use `--help` for all options. Outbound HTTPS is needed for apt,
verified runtimes, certificate issuance and Codex.

## Implementation and provenance

The bundle contains the standalone wrapper, installer, and the exact shared
gateway/toolbar/tmux source, with a SHA-256 file manifest. The bootstrap verifies
the versioned bundle; every runtime is verified against its pinned SHA-256 before
execution. Ubuntu's namespace restriction remains enabled globally; where needed,
the installer adds an AppArmor exception only for its own Codex binary.

ttyd: https://github.com/tsl0922/ttyd (MIT). Codex:
https://github.com/openai/codex (Apache-2.0). Node.js:
https://nodejs.org/ (MIT and bundled licenses). Caddy:
https://github.com/caddyserver/caddy (Apache-2.0). tmux comes from your distribution.
Runtime archives are downloaded directly from their publishers at installation.