Documentation

MarshHub Docs

Complete reference for the MarshHub static hosting platform. CLI commands, REST API, limits, and AI agent integration.

Installation Authentication CLI Commands JSON Mode REST API Limits Site Naming Error Reference

Installation

# Use without installing
npx marshub

# Or install globally
npm i -g marshub
      

Requires Node.js 18+. Single dependency: tar.

Authentication

$ marshub login
Opens https://t.me/marshubbot in browser
Press Start in Telegram to confirm
API key saved to ~/.marshubrc
      

API key is valid for 90 days. Stored in ~/.marshubrc as JSON:

{"token": "mh_...", "api": "https://marshub.uz"}

All API requests use Authorization: Bearer <token>.

CLI Commands

Command	Description
`marshub login`	Authenticate via Telegram bot
`marshub deploy`	Deploy current directory (auto-generated name)
`marshub deploy --name <n>`	Deploy with custom subdomain
`marshub ls`	List your deployed sites
`marshub status <name> <status>`	Set status: draft, preview, alpha, beta, live
`marshub rm <name>`	Delete a site (confirms interactively)
`marshub whoami`	Account info, storage, key expiration
`marshub help`	Show help

Deploy details

Packs current directory into tar.gz, uploads to server. Auto-excludes: node_modules/, .git/, .env, .DS_Store, __pycache__/.

Re-deploying the same name updates the site with a new version (last 5 kept for rollback).

You can only deploy to names you own. Deploying to someone else's name returns an error.

JSON Mode

Add --json to any command for machine-readable output. Useful for AI agents and scripts.

$ marshub ls --json
[{"name":"my-site","url":"https://my-site.marshub.uz","status":"live","size":123456,"updated_at":"..."}]

$ marshub deploy --name my-site --json
{"name":"my-site","url":"https://my-site.marshub.uz","size":123456,"version":3}

$ marshub whoami --json
{"username":"john","telegram_id":123,"sites_count":5,"storage_used":52428800,...}

$ marshub rm my-site --json
{"deleted":"my-site"}   # skips confirmation prompt
      

Errors in JSON mode output {"error":"<code>","message":"..."} with exit code 1.

Error codes: not_authenticated, token_expired, too_large, storage_exceeded, connection_failed, pack_failed, api_error.

REST API

Base URL: https://marshub.uz/api

Public

GET /api/health

Returns {"status":"ok"}

GET /api/gallery

All public sites with metadata (name, url, size, status, owner)

Authenticated (Bearer token)

POST /api/deploy

Deploy a site. Multipart form: file (tar.gz) + optional name.

Returns: {"name","url","size","version"}

GET /api/sites

List user's sites with name, url, status, size, dates

GET /api/sites/:name/files

List files in a deployed site

DELETE /api/sites/:name

Delete a site (must be owned by authenticated user)

PATCH /api/sites/:name/status

Update site status. Body: {"status":"draft|preview|alpha|beta|live"}

GET /api/versions/:name

List deploy versions for a site

POST /api/rollback/:name

Rollback to previous version

GET /api/me

User profile: username, telegram_id, sites_count, storage_used, storage_limit, api_key_expires_at

Limits

Parameter	Value
Max upload size	50 MB per deploy
Storage per user	1 GB total
Max files per site	5,000
Max sites per user	20
API key lifetime	90 days
Deploy rate limit	10 per minute

Blocked file extensions

.php .sh .bash .cgi .pl .py .rb .exe .bat .cmd .ps1 .jar .war .jsp .asp .aspx

MarshHub serves static files only. Server-side code is rejected on deploy.

Security

Path traversal protection, symlink blocking, file count limits, rate limiting, API key expiration, all requests logged.

Site Naming

Auto-generated names follow adjective-noun pattern (e.g., swift-cloud, bright-star).

Custom name rules

Rule	Detail
Length	3-30 characters
Allowed chars	`a-z`, `0-9`, `-`
No double hyphens	`my--site` is invalid
No edge hyphens	`-site` and `site-` are invalid
Uniqueness	Must be unique across the platform

Error Reference

CLI outputs errors in Russian. In --json mode, errors include a machine-readable code.

Code	HTTP	Meaning
`not_authenticated`	-	No token in ~/.marshubrc
`token_expired`	401	API key expired (90 days)
`too_large`	413	Upload exceeds 50 MB
`storage_exceeded`	507	User storage over 1 GB
`connection_failed`	-	Server unreachable
`pack_failed`	-	Failed to create tar.gz
`api_error`	4xx/5xx	Other server error