Ready to host your own world?
Download the CLI and have Cuento running in minutes.
Download Cuento CLI ↗command-line tool · self-hosted
The Cuento CLI handles everything — forking repos, provisioning your VPS, installing the database, wiring up SSL, and keeping your instance up to date — all from an interactive terminal menu.
The CLI is a single binary — no runtime, no dependencies to install on your machine. Download the binary for your OS, make it executable, and run it.
Before running the CLI, have the following ready.
A GitHub account — the CLI will fork the Cuento repositories into it and use it to manage deployments.
A Debian or Ubuntu server (1 CPU, 1 GB RAM minimum) with SSH access — root or sudo user.
A domain name with its A record already pointing to your server's IP address.
The CLI walks you through everything interactively. Run it, pick Add new project, answer the prompts, and watch the setup proceed step by step — with full resumption support if anything is interrupted.
The CLI forks the upstream Cuento backend and frontend into your GitHub account,
creates a release branch in each, and updates the GitHub Actions
workflows to deploy on push to that branch.
Over SSH, the CLI updates system packages, installs MariaDB, creates your database and user, imports the default schema, and installs Caddy as a reverse proxy with automatic SSL.
A fresh ED25519 key pair is generated. The private key is uploaded to your forks
as a GitHub Actions secret. The public key is appended to
~/.ssh/authorized_keys on the server. Future pushes to
release deploy automatically.
The backend is registered as a systemd service (cuento-backend)
running as a dedicated cuento user. It restarts automatically on
failure and starts on every boot.
The CLI prints your deployment URL. Your Cuento instance is live, SSL-secured, and ready for the first user to register.
All commands are accessed through the interactive menu — no flags to memorise. Select a project, then choose an action.
Runs all 19+ setup steps end-to-end: fork repos, configure GitHub Actions, provision the server, set up MariaDB, install Caddy, and start the backend service. If interrupted at any point, re-running picks up from the last completed step.
cuento-backend and cuento-frontend to your accountrelease branch in both forksCompares the last deployed commit in your forks against the latest upstream.
If the database schema changed, it generates migration SQL and asks for
confirmation before applying. Then merges upstream into your
release branch to trigger a fresh deploy via GitHub Actions.
main.go or .github/ changed (may need follow-up steps)Creates a new account directly in the database. Prompts for username, password (hidden input), and whether to grant admin privileges. Passwords are hashed with SHA-256 then bcrypt before storage.
Fetches the latest permissions.csv from the upstream backend and
imports all role-permission mappings into your database using
INSERT IGNORE — safe to run multiple times without creating
duplicates. Run this after any upstream update that changes permissions.
Re-writes the GitHub Actions workflow files in both forks on both
main and release branches. Use this if a Cuento
upstream update changes the CI/CD pipeline, or if your Actions stopped
triggering correctly.
All project data is saved locally in a single JSON file. The file is
readable only by the current OS user (chmod 700).
No data ever leaves your machine except what goes to your VPS and GitHub.
Each project is stored as a named entry. You can manage multiple independent Cuento instances from the same CLI.
| Field | What it stores | Notes |
|---|---|---|
| github_token | Your GitHub personal access token | Used to manage forks, secrets, and workflows |
| github_user | Your GitHub username | Resolved automatically after first auth |
| server_ip | VPS IP address | |
| ssh_user / ssh_pass | SSH login credentials | Used to connect during setup and updates |
| sudo_pass | Sudo password | Required for package installation and service setup |
| domain | Domain name | Used in Caddy config and deployment URL |
| db_root_pass / db_name / db_user / db_pass | Database credentials | MariaDB setup and backend service env vars |
| ssh_priv_key / ssh_pub_key | Generated ED25519 key pair (base64) | Stored during setup to allow step resumption |
| setup_step | Last completed setup step index | -1 = complete; positive = next step to run |
The CLI leaves your server in a clean, standard state — no custom scripts, no lock-in. All components are stock Debian/Ubuntu packages and upstream software.
Routes /api/* and /ws to the backend on port 8080.
Serves the frontend SPA on /. Handles SSL automatically.
Secured with a root password. A dedicated database and user are created. Default schema and permissions are imported on first run.
Backend runs as the cuento user, restarts on failure, and starts
automatically on every boot.
Push to the release branch in either fork to trigger an automatic
deploy to your VPS — zero manual SSH required after setup.
Download the CLI and have Cuento running in minutes.
Download Cuento CLI ↗