Documentation

MaidenVPS reference

Everything about the platform: the simulated OS, wallet-native credits, server-side AI execution, the companion runtime, and the path to rentable VPS environments.

Introduction

MaidenVPS is a Live2D AI companion operating system. It combines three layers: a browser-based simulated operating system, an AI companion runtime executing tasks server-side, and a wallet-native access model where your Solana address is your identity, your login, and your usage meter.

This documentation covers the current public build: the demo OS with 20 free daily tasks per wallet, and the VPS rental flow running in provisioning preview.

What is MaidenVPS

Most AI products are chat windows. MaidenVPS is an agentic desktop layer: tasks run inside an environment with a filesystem, a terminal, process logs, and downloadable artifacts. The companion — Maiden — is a real Cubism 4 Live2D model with physics and idle motion, docked into the OS rather than rendered as a static avatar.

The same runtime is designed to install onto real machines. The progression:

text
browser (simulated OS)  →  rented VPS (Windows / Linux / macOS)  →  full desktop runtime
Phase 01-02                 Phase 03-04                              Phase 05

Demo OS

The demo at /demo boots a simulated environment with seven apps: Terminal, Builder, Research, Summarizer, Files, Companion, and Settings. The status bar reports wallet state, remaining credits, model status, and voice status at all times.

The terminal accepts local commands and free-form tasks:

shell
❯ help                          # local, free
❯ ls                            # list simulated files, free
❯ credits                       # remaining tasks, free
❯ build a pricing page for a saas    # real task — 1 credit

Files created by tasks land in the simulated filesystem, persist in your browser, and can be downloaded individually or as a single .zip.

Wallet credits

Each connected wallet receives 20 real tasks per 24-hour window — wallets that own a VPS run at 100 tasks per day. A task is one call into the agent runtime — a build, a research brief, a summary, or a companion exchange. The window opens on your first task and the exact reset time is shown in Settings and the status bar.

http
GET /api/credits?wallet=<address>

{ "used": 3, "limit": 20, "remaining": 17, "resetAt": 1751630000000 }

No signatures

Connecting shares only your public address. The demo never requests a message signature or transaction. Optional signature verification is a planned hardening step before credits gate anything of monetary value.

AI tasks

Tasks are posted to /api/agent with the wallet address, prompt, mode, and a compact index of the simulated filesystem. The route checks credits, executes the task server-side, and returns a structured result:

json
{
  "reply": "Build complete. I scaffolded...",
  "terminal": ["mkdir projects/landing", "write projects/landing/index.html"],
  "files": [{ "path": "projects/landing/index.html", "content": "<!doctype html>..." }],
  "summary": "Scaffolded projects/landing.",
  "simulated": false,
  "credits": { "remaining": 16, "limit": 20 }
}

When no Anthropic key is configured on the server, the route degrades to a local simulated runtime that produces deterministic outputs — clearly flagged with "simulated": true — so the OS is always usable.

Voice / TTS

Maiden can speak her replies. The frontend posts text to /api/tts; the server calls ElevenLabs and streams back audio/mpeg. The voice toggle lives in the OS status bar and in Settings.

http
POST /api/tts        { "text": "Build complete." }
→ 200 audio/mpeg     (keys configured)
→ 503 tts_unconfigured  (keys missing — voice disabled gracefully)

Live2D runtime

The companion is a local Cubism 4 model (MO.moc3, 16 textures, physics, and five motion files) served from the site itself and rendered with PixiJS. The runtime adds:

  • Cursor tracking — smooth head and eye follow across the window
  • Idle motion — the shipped motion set registered as the idle group
  • Physics — hair and body dynamics from the model's physics3 definition
  • Graceful fallback — a styled placeholder if WebGL or the core script fails

Asset note

The model weighs roughly 86 MB across its texture atlas, so first load streams for a few seconds on slower connections. It is cached aggressively afterward.

VPS rental concept

Four plans are priced in SOL — Linux (0.25), Windows (0.6), macOS (1), and the dedicated-GPU Hyperstation (3). Checkout follows a conventional order flow:

http
GET  /api/vps/plans          # plan catalog
POST /api/payments/create    # payment intent: amount, treasury, reference
POST /api/payments/verify    # on-chain check: signature, recipient, amount
POST /api/vps/rent           # issue the machine record + credentials

Payment is a real SOL transfer signed in Phantom. The server independently verifies the transaction on-chain before the order is created; you receive the hostname, IP, and access credentials on completion and in your dashboard.

Security model

  • Wallet is login. No email or password database exists.
  • Secrets never leave the server. Anthropic, ElevenLabs, and future provider keys are read from environment variables inside API routes only. The browser communicates exclusively with internal endpoints.
  • Credits are enforced server-side. The client renders the meter; the server is the authority.
  • Payments require explicit confirmation. Real provisioning will verify the on-chain transfer — recipient, amount, and finality — before any machine is allocated.

Environment variables

Copy .env.example to .env.local. Server-side variables must never be prefixed with NEXT_PUBLIC_.

dotenv
# server-side only — never exposed to the client
ANTHROPIC_API_KEY=            # enables live AI execution
ANTHROPIC_MODEL=claude-opus-4-8
ELEVENLABS_API_KEY=           # enables voice
ELEVENLABS_VOICE_ID=
DATABASE_URL=                 # swaps the dev store for Postgres
VPS_PROVIDER_API_KEY=         # Phase 04 — real provisioning
PAYMENT_TREASURY_WALLET=      # Phase 03 — real payments

# client-safe
NEXT_PUBLIC_SOLANA_NETWORK=mainnet-beta

Every integration degrades gracefully while its variables are missing: AI falls back to the simulated runtime and voice disables itself. Payments always verify on-chain against the treasury address.

Future provider integration

Phase 04 replaces the preview endpoints with a real provider pipeline: payment verified on-chain, machine allocated via the provider API, base image flashed, the MaidenVPS runtime installed, and credentials delivered to your dashboard — targeted at minutes from payment to desktop. The API surface (/api/vps/*, /api/payments/*) is already shaped for this swap.

FAQ

Common questions — free tasks, signatures, key handling, provisioning status — are answered on the FAQ section of the home page. Anything deeper is covered by the sections above.