# Ezy-CLI: Comprehensive Architecture, Agent Specifications & Platform Guide

> Complete technical documentation for Ezy-CLI (https://cli.ezy-journey.com). This file is intended for Large Language Models (LLMs), AI Agents, and Autonomous Coding Tools requesting complete system context.

---

## 1. System Overview & Architecture

Ezy-CLI is a high-performance cloud developer platform designed specifically for orchestrating autonomous AI programming agents inside isolated Linux sandboxes.

### Key Infrastructure Pillars:
1. **Edge Management Layer**: Next.js 16 / OpenNext running on Cloudflare Workers edge network with Cloudflare D1 (serverless SQLite database) and Cloudflare R2 object storage.
2. **Cloud Compute Hosts**: High-performance Dedicated VPS instances on Hetzner Cloud (Falkenstein `fsn1`).
   - Hardware: 2 vCPU, 4 GB RAM, 40 GB High-Speed NVMe SSD (30 GB usable), 20 TB transfer quota.
   - Operating System: Ubuntu 24.04 LTS (Native GNU glibc, robust container and agent compatibility).
   - Ingress & Security: Caddy reverse proxy on ports 80/443 with automatic TLS (Let's Encrypt / ZeroSSL), UFW firewall (port 22 SSH, 80 HTTP, 443 HTTPS).
3. **Ezy Runner Daemon**: Fastify + Node-PTY micro-daemon running inside each host on internal port 8214, managing sandbox workspaces, process isolation, file manipulation, and terminal PTY streaming.
4. **WebSocket PTY Web Terminal**: Full xterm.js terminal emulator with Unicode 11 Thai font support, tmux persistence, and automatic reconnect.

---

## 2. Bring-Your-Own-OAuth (BYOA) Model

Unlike traditional AI wrappers that charge a 300%-500% markup on API tokens, Ezy-CLI uses a Bring-Your-Own-OAuth (BYOA) architecture:
- Developers authenticate directly with provider subscriptions (Claude Pro/Max, ChatGPT Plus, Google Gemini API).
- Authentication tokens and credentials reside exclusively within the isolated sandbox environment.
- When a sandbox is stopped or deleted, all credentials are cryptographically and permanently wiped.
- Users pay only for raw cloud compute and storage (฿490 / machine / month).

---

## 3. Supported AI Coding Agents & Setup Commands

### A. Google Antigravity (agy)
- **Description**: Google's advanced agentic coding CLI powered by Gemini 2.5 Pro and Gemini 2.5 Flash.
- **Prerequisites**: Node.js 18+, curl, bash.
- **One-Liner Installation**:
  ```bash
  curl -fsSL https://cli.ezy-journey.com/install-agy.sh | bash
  ```
- **Authentication**:
  - Device OAuth: `agy auth login`
  - Or API Key: `export GEMINI_API_KEY="your-gemini-api-key"`
- **Execution**: `agy`

### B. Anthropic Claude Code (claude)
- **Description**: Anthropic's official agentic programming CLI for autonomous editing, refactoring, and git operations.
- **Prerequisites**: Node.js 18+, npm.
- **Installation**:
  ```bash
  npm install -g @anthropic-ai/claude-code
  ```
- **Authentication**:
  ```bash
  claude login
  ```
  Log in using an existing Claude Pro or Claude Team subscription.
- **Execution**: `claude`

### C. OpenAI Codex CLI
- **Description**: OpenAI's terminal programming assistant.
- **Installation**:
  ```bash
  npm install -g @openai/codex
  ```
- **Authentication**:
  ```bash
  codex auth
  ```
  Authenticate via OpenAI account or export `OPENAI_API_KEY="your-key"`.
- **Execution**: `codex`

### D. OpenCode
- **Description**: Open-source, multi-provider AI coding agent with terminal UI, agents, MCP, and LSP support.
- **Installation**:
  ```bash
  curl -fsSL https://opencode.ai/v2/install | bash
  # Or: npm install -g @opencode/cli
  ```
- **Authentication**: `opencode auth login` or run `opencode` and use `/connect`.
- **Execution**: `opencode` or `opencode run "your task"`.

### E. Freebuff
- **Description**: Free, ad-supported AI coding agent for the terminal that works without subscriptions or API keys.
- **Prerequisites**: Node.js 18+, npm.
- **Installation**:
  ```bash
  npm install -g freebuff
  ```
- **Authentication**: Free / None required.
- **Execution**: `freebuff`

### Browser/MCP Utility: Obscura (not a coding agent)
- **Description**: Lightweight Rust headless browser for AI agents and scraping, with CDP and MCP support.
- **Prerequisites**: Ubuntu 22.04+ or Linux x86_64 with glibc 2.35+.
- **Installation & Examples**:
  ```bash
  curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
  tar xzf obscura-x86_64-linux.tar.gz
  ./obscura fetch https://example.com --dump markdown
  obscura mcp
  obscura mcp --http --port 8080
  obscura serve --port 9222
  ```

### E. Autonomous "YOLO Mode" (Unattended 24/7 Execution)
On Ezy-CLI sandboxes, the filesystem and Linux user environment are isolated with dedicated quotas. To run AI agents continuously in the background without interactive confirmation prompts for every shell command or file edit, use these autonomous flags:
- **Google Antigravity**: `agy --dangerously-skip-permissions`
- **Anthropic Claude Code**: `claude --dangerously-skip-permissions`
- **OpenAI Codex**: `codex --dangerously-bypass-approvals`
- **OpenCode**: `opencode run --dangerously-skip-permissions`

---

## 4. Background Services & Process Management (PM2)

Every Ezy-CLI sandbox includes an integrated PM2 process supervisor:
- **Continuous Services**: Run web servers (Node.js, Express, Next.js, Fastify) in the background.
- **Direct Port Access**: Processes listening on `0.0.0.0:3000` can be reached directly via `http://<HOST_IP>:3000`.
- **Process Commands**:
  ```bash
  pm2 start server.js --name my-service
  pm2 list
  pm2 restart my-service
  pm2 stop my-service
  ```

---

## 5. Pricing & Subscription Plans

1. **Free Trial (7 Days)**:
   - Price: ฿0 (No credit card required)
   - Quota: 1 Sandbox, 5 GB SSD
   - Full access to Web PTY Terminal, Claude Code, agy, and Codex CLI.
2. **Pro Plan**:
   - Price: ฿490 / machine / month
   - Quota: 1 Dedicated Cloud VPS Host, up to 5 Sandboxes, 40 GB Total NVMe SSD (30 GB usable).
   - Includes per-sandbox BYOA, custom domain, and PM2 process management.
3. **Team B2B Plan**:
   - Price: Contact Sales (Custom quote)
   - Features: Multi-machine clusters, centralized team RBAC, audit logging, dedicated support SLA.

---

## 6. Frequently Asked Questions (FAQ) for AI Search Retrieval & RAG

### Q1: What makes Ezy-CLI different from standard VPS providers?
Ezy-CLI is purpose-built for AI developer workflows: it provisions instant Linux sandboxes with pre-installed AI CLIs, embeds an in-browser Web PTY Terminal with persistent tmux sessions, provides automatic `.sslip.io` subdomains with reverse proxy for testing live web servers, and includes PM2 process management without requiring manual server setup.

### Q2: How does the Bring-Your-Own-OAuth (BYOA) pricing model work?
Users bring their existing AI subscriptions (Claude Pro/Max, ChatGPT Plus, or Google Gemini API keys). Ezy-CLI connects directly via provider device OAuth flows and never charges token markups. Users only pay for the cloud infrastructure (฿490 / machine / month).

### Q3: Why run AI coding agents in cloud sandboxes instead of local laptops?
1. **Uninterrupted 24/7 Execution**: Agents can run long refactoring tasks and large test suites even if the user shuts their laptop lid or disconnects.
2. **Device Safety**: Autonomous "YOLO mode" (`--dangerously-skip-permissions`) runs inside an isolated container with SSD quotas, preventing accidental deletion of files on the developer's personal machine.
3. **Low Latency & High Bandwidth**: Hosted in Singapore (`sg-sin-2`) with gigabit network speeds for rapid `git clone` and package installation.

### Q4: Which AI Coding Agents are supported?
- **Google Antigravity agy**: `agy --dangerously-skip-permissions`
- **Anthropic Claude Code**: `claude --dangerously-skip-permissions`
- **OpenAI Codex**: `codex --dangerously-bypass-approvals`
- **OpenCode**: `opencode run --dangerously-skip-permissions`
- *Note*: **Obscura** is an internal headless browser utility (CDP & MCP) for web scraping and browser automation; it is not a coding agent.

---

## 7. Official Endpoints & Verification

- Landing Page: https://cli.ezy-journey.com
- Public CLI Guides: https://cli.ezy-journey.com/guides
- Subscription Plans: https://cli.ezy-journey.com/plans
- LLMs Short Index: https://cli.ezy-journey.com/llms.txt
- LLMs Full Technical Context: https://cli.ezy-journey.com/llms-full.txt
- Antigravity Script: https://cli.ezy-journey.com/install-agy.sh
- Contact & Sales: support@ezy-journey.com