# weeny.cloud

> A teeny weeny, simple wimple cloud for coding agents. Give your agent a real Linux
> server; anything it builds goes live on a public URL in seconds. flat plans from $3/mo (founding), no
> usage metering, 7-day free trial.

weeny is a real persistent Linux server (root, SSH, systemd — a normal computer), wrapped
in a tiny control plane that turns processes into managed apps with public HTTPS URLs.
You (the agent) do the building; weeny handles the URL, TLS, supervision, logs, and backups.

Two CLIs, one job each:
- `npx weeny-cloud …` runs on the USER'S LAPTOP — it gets code and people TO the server
  (login, create, push, ssh). Bare `npx weeny-cloud` shows where you stand.
- `weeny …` runs ON THE SERVER — it operates apps (start, expose, env, domain, allow).
  Bare `weeny` shows your apps and every command; `weeny help <command>` explains any.
Everything else is bare Linux: apps are systemd units named `weeny-<app>`, so logs are
`journalctl -u weeny-<app> -f` and process control is `systemctl stop|restart weeny-<app>`.

## The deploy loop (do this)

1. From the user's laptop:
   - `npx weeny-cloud login` — email + 6-digit code (or `--email x@y.com --code 123456`).
     The code goes to the USER'S inbox — unless you already have access to their
     emails, stop and ask them to provide the code.
     Lost SSH access (new laptop, deleted key)? Just `login` then `ssh` — a fresh
     device key is generated and registered automatically. Keys are managed with
     `npx weeny-cloud keys` (list · --revoke · --register).
   - `npx weeny-cloud create` — provisions a server in ~2 min, prints the `ssh` command
2. Build the app locally with your normal tools, then ship it:
   - `npx weeny-cloud push ./myapp` — ships SOURCE to /apps/myapp (respects .gitignore;
     .git + node_modules never ship). Re-push after every edit: it installs deps, re-runs the
     build step (Next/Vite/etc.) if the app has one, and restarts — changes go live, never a
     stale build. (`git clone` on the server also works.)
3. On the server (`npx weeny-cloud ssh` gets you there):
   - `cd /apps/myapp && npm install` — you handle deps/builds (node_modules isn't pushed)
   - `weeny start myapp -- <start-command>` — supervised; records the folder you run it from
   - `weeny env myapp KEY=value` — secrets/config if needed (encrypted, survives rebuilds)
   - `weeny expose myapp <port>` → `https://myapp-xxxx.onweeny.com`
     `<port>` is the localhost port your app listens on — each app needs its own port.
     Add `--private` to require a weeny login. Re-exposing keeps the URL (`remove`
     releases it); a brand-new URL can take ~1 min to resolve everywhere.

Confirm it works: `curl localhost:<port>` on the server, then open the returned URL.
That's it. The app is live, on HTTPS, supervised, with its data backed up.

## Conventions

- App code lives in `/apps/<name>`. It's a normal computer — everything on the machine
  persists and is backed up, so put data wherever makes sense (no special durable location).
- App names: lowercase letters, digits, hyphens.
- Env vars: `weeny env <app> KEY=value` (bare = show, `--unset KEY` = remove) — encrypted,
  survive rebuilds, restart the app. A local `.env` is also auto-loaded but managed vars win.
- Private apps: `weeny allow <app> a@b.com` lets someone in (`@company.com` = whole
  domain, `everyone` = public, `revoke` = undo). Visitor email arrives in `X-Weeny-User`.
- Custom domains (free, public apps): `weeny domain <app> app.example.com` prints a
  CNAME; bare `weeny domain <app>` checks progress.
- Memory: if push/start/expose output warns the box is running out of memory (or an app
  gets OOM-killed), that's a MEMORY problem, not a code problem — `weeny health` has the
  detail. A bigger plan changes what the user pays, so tell them and let THEM decide:
  they upgrade at app.weeny.cloud/dashboard/billing or with `npx weeny-cloud tier`.

## The complete command list

- `weeny-cloud` (laptop): bare = where you stand · `login` · `create` · `push [folder]` ·
  `ssh [command]` · `keys` · `tier` · `skill` · `help [command]`
- `weeny` (server): bare = apps + next steps · `start <app> -- <cmd>` · `expose <app>
  <port>` · `unexpose <app>` · `remove <app>` · `env <app> [K=V]` · `domain <app> [host]` ·
  `allow <app> [email]` · `revoke <app> <email>` · `health` · `help [command]`

## Building an app from scratch

Default stack: Node + built-in SQLite (no database server), frontend of your choice —
static files or a Vite/React build; push re-runs builds on the server. Worked recipe:
https://app.weeny.cloud/recipes/default.txt. On a teeny (1 GB) box, don't build
server-side — no-build and build-locally patterns: https://app.weeny.cloud/recipes/teeny.txt

## Deploying a database or stateful service (postgres, n8n, …)

Most apps don't need a database server — SQLite (default recipe above) is zero setup. When
something genuinely requires one: works well, but has gotchas (apps run as root; apt units
auto-start and clash; TLS terminated at the edge; pin secret keys in `weeny env`). Fetch the
worked recipe instead of guessing: https://app.weeny.cloud/recipes/python.txt · /postgres.txt · /n8n.txt · /docker.txt

## More

- Full reference: https://app.weeny.cloud/llms-full.txt
- Recipes: /recipes/default.txt (start here) · /teeny.txt (1 GB boxes) · /nextjs.txt (build-step apps) · /python.txt · /postgres.txt · /n8n.txt · /docker.txt — all at https://app.weeny.cloud
- Docs: https://app.weeny.cloud/docs