xCloud Terminal

xCloud Terminal (xterm) is the planned Ubuntu-installable terminal experience for xCloud:

• Direct mode: deterministic xcloud/xterm commands for scripts, CI, and DevOps runbooks.
• AI mode: a Claude Code-style agent shell opened with xcloud --ai, xterm --ai, xterm agent, or xterm chat.
• Bundled CLI: @xcloud/cli is a default dependency, so xCloud Terminal ships with direct xCloud commands by default.
• Same xCloud capabilities: the AI agent must use the same safe xCloud API/tool layer as direct commands, not a separate unsafe bypass.

This repository is intentionally separate from the Laravel app and builds on the standalone xCloudDev/xCloud-cli package.

Target UX

# Direct deterministic commands
xcloud servers list
xterm servers list
xterm sites status <site-uuid>
xterm api get /servers --output json

# AI agent shell
xcloud --ai
xterm --ai
xterm agent
xterm chat "Create a WordPress site on my smallest Hetzner server"

# Agent backend/mode switching
xterm --ai --agent local
xterm --ai --agent hosted --skills-repo https://github.com/xCloudDev/xcloud-agent-skills

# Safe writes need confirmation or --yes in non-interactive mode
xterm --ai --yes "purge cache for example.com"

AI provider setup

OpenRouter-compatible setup mirrors the xCloud AI branch naming while keeping portable XCLOUD_AI_* aliases:

export OPENROUTER_API_KEY="..."
export OPENROUTER_API_URL="https://openrouter.ai/api/v1"
export XCLOUD_AI_MODEL="anthropic/claude-sonnet-4.5"

xterm doctor
xterm --ai "why is my site down? give me safe read-only checks first"

Supported aliases:

• Provider: XCLOUD_AI_PROVIDER or AI_PROVIDER
• API key: XCLOUD_AI_API_KEY or OPENROUTER_API_KEY
• Base URL: XCLOUD_AI_BASE_URL, OPENROUTER_API_URL, or OPENROUTER_BASE_URL
• Model: XCLOUD_AI_MODEL, OPENROUTER_AGENT_MODEL, or OPENROUTER_DEFAULT_MODEL

Current AI mode is intentionally terminal-side and safe: it answers and suggests explicit xterm/xcloud commands. Automatic tool execution is the next layer and must use the same Public API/CLI capability and confirmation model from issue #5099.

Install target

npm install -g @xcloud/terminal
xterm --help
xcloud --ai

@xcloud/terminal exposes both xterm and xcloud binaries. Direct xcloud commands delegate to the bundled @xcloud/cli; xcloud --ai opens xCloud Terminal agent mode.

Homebrew and apt/deb packaging are planned after the first working release.

Current status

The repo now has:

• working direct-command delegation through bundled @xcloud/cli
• a real terminal-side AI entrypoint for one-shot prompts (xterm --ai "..." / xcloud --ai "...")
• OpenRouter-compatible configuration aligned with the Laravel AI branch:
  • OPENROUTER_API_KEY
  • OPENROUTER_API_URL=https://openrouter.ai/api/v1
  • OPENROUTER_DEFAULT_MODEL or XCLOUD_AI_MODEL
• xterm doctor to verify AI configuration without printing secrets

The detailed branch analysis, architecture, and execution plan are in:

• docs/BRANCH-ANALYSIS.md
• docs/ARCHITECTURE.md
• docs/IMPLEMENTATION-PLAN.md