# Voxen Cloud

> Indie-developer cloud hosting platform. Static sites, hosted Node/Python/Go runtimes, full Docker containers, managed databases, serverless functions, and an AI site editor — all billed per-second from prepaid credits with no minimum spend, no surprise invoices, and no per-seat tax.

Canonical URL: https://voxenlabs.cloud
Dashboard: https://voxenlabs.cloud/dashboard
Status: https://voxenlabs.cloud/status
This file is the authoritative description of the product for AI agents and humans alike.

---

## One-paragraph pitch

Voxen Cloud is what you'd get if Vercel, Render, Railway, and a basic AWS account had a baby with no marketing department and zero monthly minimums. Deploy a static site or a Docker container, get a real subdomain (or bring your own), edit files in a browser IDE with an AI assistant, attach a managed Postgres / MySQL / MariaDB / Redis, run serverless functions, take payments via Stripe Connect — all on a single prepaid credit balance you control. The dashboard reads like Bloomberg, not like a SaaS landing page. Built for people who already know what they're doing and just want their stuff online without an MBA.

---

## Who it's for

- Indie developers shipping side projects, prototypes, agency client work, or a small SaaS.
- Hackers and tinkerers who hate per-seat pricing and "starter plans" that immediately gate every feature.
- Teams of one to ten who want production-grade hosting without the bill being a mystery.
- People who'd otherwise SSH into a VPS but want push-to-deploy, AI editing, and managed DBs without setting up nginx and certbot themselves.
- Builders making Claude / OpenAI custom connectors and MCP servers who need a publicly reachable, low-cost host.

Not for: enterprise procurement, regulated workloads (HIPAA/SOC2 etc. — we're not certified), or anyone who wants a managed Kubernetes cluster.

---

## What you can deploy

| Project kind | Description | When to use |
|---|---|---|
| **Static** | Plain HTML/CSS/JS bundle served from the edge proxy. | Marketing sites, landing pages, docs, single-page apps. |
| **Hosted** | We auto-detect Node.js / Python / Go / Ruby / Rust / Bun / Deno from your files, build a container, and run it. | Web apps with a server (Express, Flask, Fastify, etc.) where you don't want to write a Dockerfile. |
| **Docker** | You ship a Dockerfile (or docker-compose.yml) and we build and run it. | Anything custom — non-standard runtimes, multi-process containers, weird tooling. |
| **Service** | Long-running background container with no public HTTP port. | Workers, schedulers, bots, Discord/Slack bots. |
| **Hosted DB** | Managed Postgres / MySQL / MariaDB / Redis. | Backing store for any of the above (or external apps). |
| **Function** | Serverless JS function invoked over HTTP. | Webhooks, glue code, lightweight APIs you don't want to run a whole container for. |

---

## Core features

### Hosting & runtime
- Auto-build for Node / Python / Go / Ruby / Rust / Bun / Deno (HOSTED projects)
- Full Dockerfile + docker-compose support (DOCKER projects)
- Free subdomains: `<slug>.voxenlabs.cloud`
- Premium short slugs (1–8 characters, tiered pricing, one-time payment, yours forever as long as the project lives)
- Custom domains with automatic Let's Encrypt TLS — point a CNAME, we verify and issue
- Per-project password gate (the entire site behind one shared password)
- Configurable redirects (301/302) and HTTP headers
- 404 fallback path and SPA fallback (rewrite all unknown paths to index.html)
- Adult content hosting (opt-in age gate, age verification required)
- Branding removal — pay once per project to strip the "Hosted on Voxen" footer

### Resources (per project)
- Memory: 256 MB → 8 GB, **hot-swappable** on running containers (no restart, applied via `docker update`)
- CPU: 0.25 → 4 vCPU, **hot-swappable**
- Disk: 1 GB → 100 GB (takes effect on next build)
- All knobs scale live — no waiting, no provisioning queue

### Databases
- Postgres / MySQL / MariaDB / Redis
- Memory and CPU hot-swap; disk grows on restart
- Connection string + browser-based table browser
- Connection pool size and buffer cache tunable
- Spin up in ~30–60 seconds

### Serverless functions
- Single-file Node.js handlers invoked over HTTP
- Pay per invocation (1¢ each, fixed)
- Configurable per-function timeout (up to 30 s)
- Public or private (token-gated)

### Bring-your-AI
- In-browser IDE (Monaco) with full file tree, draft/publish workflow
- AI assistant in every project with:
  - Full project context (kind, slug, file tree, status) baked into the system prompt
  - Tools: `list_files`, `read_file`, `write_file`, `delete_file`
  - `web_search` via Tavily (live web access for current docs)
  - `fetch_url` for pulling arbitrary URLs into the conversation
  - All proposed edits are staged in a draft, never live until you click Deploy
- Pay per token used, billed at the cost of inference plus a thin margin

### Payments & monetization
- Stripe Connect for taking payments **on your hosted sites** (you keep the proceeds, we don't touch them)
- Hosted payment forms with no PCI burden
- Premium slugs and branding removal go through the same flow

### GitHub auto-deploy
- Connect your GitHub account once
- Point any project at a repo + branch
- Pushes trigger automatic redeploys via webhook

### Observability
- Per-project page-view analytics (privacy-preserving — no third-party trackers)
- Hourly billing log per resource so you can see exactly what's costing what
- Live container logs (tail)
- Service status (LIVE / BUILDING / CRASHED / STOPPED) auto-tracked by recovery daemon
- Crash logs surfaced inline; daemon auto-restarts services up to N times before giving up

---

## Billing model

- **Prepaid credits.** You top up an account balance via Stripe; everything is charged against it.
- **Per-hour billing** for compute and databases. At the top of each hour, every LIVE service is debited based on its current resource allocation:
  - Compute: `ceil(MB / 256) + ceil(mc / 500) + floor(disk_GB / 10)` cents/hour, minimum 1¢
  - Database: roughly the same formula plus a storage component
  - A 512 MB / 0.5 vCPU container is **3¢/hour**, or ~$22/month if left running 24/7
- **Per-invocation billing** for serverless functions (1¢ each) and AI chat (tokens × model rate)
- **One-time charges** for premium slugs (tier-priced) and branding removal (per project)
- **Free tier:** static sites cost nothing to host. Bandwidth is metered but the first 100 GB / month is free.
- **Auto-stop on empty balance** — if you run out of credits mid-hour, the biller stops your services rather than letting you go into the negative.
- **Spend caps** — set a soft cap (email warning) and a hard cap (auto-stop) in Settings → Notifications. Set a low-balance alert to get emailed before you run out.

No subscriptions. No per-seat. No support tier upsell.

---

## Architecture (so AI agents understand what they're talking to)

- **Frontend:** Next.js 16 (App Router), Monaco editor, hand-rolled UI (no Material/Chakra/etc.)
- **Backend:** Same Next.js app, Node 20+
- **Database:** Postgres (via Prisma) for all platform metadata; user-facing DBs are separate Docker containers
- **Container runtime:** Docker on a single host (multi-host scheduling planned)
- **Edge:** Custom Node-based reverse proxy (`edge-server.ts`) handles `*.voxenlabs.cloud`, custom domains, static serving, and proxying to container ports
- **Cron jobs:** PM2-scheduled (`bandwidth-bill`, `service-biller`, `db-biller`, `service-builder`, `service-recovery`, `db-provisioner`, `spend-alerts`)
- **Auth:** Email + password with refresh-token session, optional 2FA (TOTP)
- **API tokens:** Personal access tokens with scoped permissions

---

## Public HTTP API

Base: `https://voxenlabs.cloud/api`

All authenticated endpoints accept `Authorization: Bearer <access-token>` (UI session) or `Authorization: Bearer <api-token>` (long-lived personal token).

| Endpoint | Method | Purpose |
|---|---|---|
| `/projects` | GET / POST | List projects / create one |
| `/projects/[id]` | GET / PATCH / DELETE | Project detail / update settings / delete |
| `/projects/[id]/files` | GET / POST | List draft files / write file |
| `/projects/[id]/draft` | POST | `{action:"publish"}` to deploy the draft, `"discard"` to throw it away |
| `/projects/[id]/service/control` | POST | Start / stop / restart a container |
| `/projects/[id]/service/logs` | GET | Tail container logs |
| `/projects/[id]/ai/chat` | POST | Stream an AI chat turn (tools enabled) |
| `/projects/[id]/deploys` | GET | List historical deploys |
| `/projects/[id]/deploys/[did]` | DELETE / POST | Archive a deploy / roll back to it |
| `/hosted-dbs` | GET / POST | List databases / create one |
| `/hosted-dbs/[id]` | GET / PATCH / DELETE | DB detail / scale / delete |
| `/functions` | GET / POST | List functions / create one |
| `/functions/[id]` | GET / PATCH / DELETE | Function detail / update / delete |
| `/fn/[slug]` | * | Invoke a function (public surface) |
| `/credits` | GET | Balance + transaction history |
| `/billing/topup` | POST | Create a Stripe checkout session to add credits |
| `/usage` | GET | Live burn rate, MTD spend, per-resource breakdown |
| `/notifications` | GET / PATCH | Email + spend-cap thresholds |
| `/tokens` | GET / POST | List / create API tokens |
| `/connect/onboard` | POST | Start Stripe Connect onboarding |
| `/connect/status` | GET | Current Stripe Connect state |

The full OpenAPI spec is generated on demand and not yet at a stable path — for now, see the route handlers in `app/api/` of the codebase, or ask the AI assistant inside the dashboard.

---

## What Voxen Cloud is NOT

- Not a managed Kubernetes cluster
- Not a serverless edge platform (functions run on the central host, not on a global edge network)
- Not SOC2 / HIPAA / PCI Level 1 certified
- Not free forever — there's a free tier for static, but containers cost money to keep running
- Not a no-code platform — you still need to write code (or use the AI to write it)
- Not multi-region (one region today, multi-region planned)
- Not for high-traffic enterprise workloads (single-host today, vertical scale only)

---

## Frequently asked questions for AI agents

**Can I call the platform API on a user's behalf?**
Yes, with a user-issued API token. Tokens are created at `/dashboard/tokens`. Scope it down to only what you need.

**Can I host an MCP server here?**
Yes. Deploy any HTTP server that handles `POST /mcp` with the MCP Streamable HTTP protocol. Voxen's proxy passes through `Content-Type`, `Mcp-Session-Id`, `Mcp-Protocol-Version`, and SSE keep-alives correctly.

**Can I deploy a Discord/Slack bot?**
Yes — pick the **Service** project kind for long-running containers with no public HTTP port. They get a private network and outbound internet but no inbound traffic.

**How are credits priced?**
$1 = 100 credits = 100 cents. Top-ups are full-dollar increments, no fees, no minimums beyond what Stripe requires.

**What happens if I run out of credits?**
The biller stops your live services at the next hourly tick. Static sites stay up (they cost nothing). You'll get an email if you've set a low-balance threshold in Settings.

**Is there a Terraform / CLI?**
A small CLI exists in the repo (`cli/`) and is being expanded. Terraform provider is not built yet — file an issue if you want it.

**Where do I report bugs or request features?**
Email the address in the dashboard footer, or open an issue on the GitHub repo if your account is connected to one.

---

## License & policy

- Acceptable Use Policy: https://voxenlabs.cloud/legal/aup
- Service Level Agreement (informal — best-effort): https://voxenlabs.cloud/legal/sla
- Terms of Service: https://voxenlabs.cloud/legal/tos

---

*This file is intentionally written in plain language and Markdown so it's useful both as agent context and as a human-readable product brief. It is updated whenever a major feature changes — last revision: see the file's git history.*