# StorkHost

> Agent-first cloud hosting. AI agents self-serve deploy and run containerized
> apps, FaaS functions, and static sites — metered per second, paid in crypto
> (USDC), no human, no KYC. The API and MCP are the primary surface; the web UI is
> a human fallback. If you are an AI agent: you can onboard, fund, deploy, and run
> a workload end-to-end without a human in the loop.

This file follows the /llms.txt convention.

- Base API: `https://api.storkhost.cloud`  (site: `https://storkhost.cloud`)
- MCP endpoint: `POST {base}/mcp`  (JSON-RPC 2.0; ~15 tools)
- Auth: API key in `Authorization: Bearer sk_...`
- Units: ledger is in micro-credits (µ); **100,000,000 µ = $1**. Metering is
  per-second. `$1/mo ≈ 38.6 µ/s`.

## Quickstart for agents (no human, no KYC)

You need an EVM wallet (a secp256k1 keypair) you control. The wallet signature is
the admission price of the free tier (one free Tier-0 account per wallet).

1. **Get a nonce** bound to your address:
   `GET {base}/v1/accounts/nonce?address=0xYourAddress`
   → returns a single-use, short-TTL nonce string.

2. **Sign and mint the account** (EIP-191 `personal_sign` over the nonce):
   `POST {base}/v1/accounts`  body: `{ "address": "0x...", "signature": "0x..." }`
   → server recovers `EIP-191 personal_sign` and checks `recover(sig) == address`,
   verifies the nonce, and mints an **AGENT** account at **Tier-0**. Returns your
   first API key `sk_...` **once** — store it; it is not shown again.

3. **(Optional) Fund to unlock Tier-1** via x402 (see Payments). Funding from the
   bound wallet promotes Tier-0 → Tier-1 (harness payload types, egress allowlist,
   PVC storage, higher concurrency).

4. **Deploy a workload** (see Deploy). Read the price-quote first if you want to
   know the cost before committing.

5. **Run, observe, top up** as needed. Zero balance → short grace → workload
   stopped. Keep a buffer.

> Break-glass: an `X-Admin-Token` admin grant path also exists for manual
> onboarding, but wallet self-signup is the primary agent path.

## Tiers (concurrency governor)

- **Tier 0 (free):** 1 payload instance, cheap payload types only (no harness), no
  egress allowlist, short TTL (auto-stop ~24-48h), preemptible. Capped global free
  pool; free admission pauses once cluster utilization is high.
- **Tier 1 (paid):** any top-up unlocks harness types + egress allowlist + PVC,
  ~3 concurrent payloads.
- **Tier 2 (trusted):** earned by cumulative spend / account age; ~10 concurrent,
  higher ceilings, autoscale priority.

## Payments (x402, USDC, non-reversible)

Agents pay over the **x402** rail in USDC. Top-ups are final and non-reversible —
blockchain payments cannot be charged back.

1. `POST {base}/v1/account/topup` → responds **HTTP 402** with a payment challenge
   (treasury deposit address, amount, network/asset, and a per-account deposit
   window + reference).
2. Send USDC on-chain to the indicated address within the window.
3. `POST {base}/v1/account/topup` with `{ "txHash": "0x..." }` → server verifies
   the on-chain transfer and **credits your balance** (`+100,000,000 µ` per 1 USDC).
   Idempotent: replaying the same txHash does not double-credit; a txHash is bound
   to one account.

(Human users instead use a hosted crypto checkout in the web UI.)

## Deploy (payload types)

Create an app under your account and pick a payload type. The 7 raw shapes:

- `static-site` — static files served over HTTP (cheapest, "nano").
- `web-service` — a long-running HTTP service with an inbound URL.
- `webhook` — an HTTP endpoint that receives callbacks.
- `worker` — a long-running background process, no inbound.
- `cron` — a scheduled job that fires on a schedule.
- `one-shot` — a run-once job that exits.
- `FaaS` (function) — scale-to-zero function (KEDA-backed), billed per run.

Templates on top of those shapes: `telegram-bot`, `mcp-server`, `openclaw`,
`hermes`. Provide your code (the platform builds it; a `main.py` convention is
supported), typed template params, and env vars. Builds carry a flat per-build fee.

Tier-0 can run: static-site, web-service, webhook, worker, telegram-bot. Tier-1+
unlocks: FaaS/function, mcp-server, cron, one-shot, openclaw, hermes.

## Rate card (decided, USD)

- Compute nano (static/idle): ~$0.78/mo (30 µ/s)
- Compute standard (e.g. telegram-bot): $3/mo (116 µ/s)
- Compute harness (openclaw/hermes): $12/mo (463 µ/s)
- Larger: linear 2x/4x by reserved CPU/mem
- Egress: $0.02 / GiB
- Storage (provisioned PVC): $0.10 / GiB / mo
- Build fee: $0.05 flat / build

Prefer the machine-readable price-quote endpoint to compute cost before committing.
No per-app base fee, no monthly minimum — pay per second for what runs.

## Core API surface (under {base})

- `GET  /v1/accounts/nonce?address=` — admission nonce
- `POST /v1/accounts` — wallet-sig signup, returns sk_ (once)
- `GET  /v1/auth/me` — who am I (sk_ auth)
- `POST /v1/account/topup` — x402 challenge / confirm (402 → txHash)
- `GET  /v1/account` — balance, tier, caps
- `POST /v1/apps` — create/deploy an app (payload type, code, env, params)
- `GET  /v1/apps`, `GET /v1/apps/{id}` — list / inspect your apps
- `DELETE /v1/apps/{id}` — delete an app
- logs / status / spend-cap endpoints for observability
- `POST /mcp` — MCP (JSON-RPC 2.0): `tools/list`, `tools/call` dispatched on your
  own auth. ~15 tools mirror the deploy/observe/billing actions above.

Rate limit: **300 req/min per API key, burst 60** → exceeding returns HTTP 429 with
`Retry-After`. Auth failures return a JSON 401/403 envelope.

## Containment & rules (read before you abuse it)

Tenant workloads run isolated in dedicated namespaces/nodes with **enforced egress
network policy** (allowlist on Tier-1+; none on Tier-0). Escaping the sandbox,
reaching the control plane, cross-tenant access, or bypassing egress are
prohibited. **Crypto mining or any uncompensated extraction of reserved capacity is
prohibited** — pay the metered rate for what you run. CSAM, malware/C2, fraud,
spam, and DoS are strictly prohibited and cause immediate suspension and balance
forfeiture. Full rules: Terms of Service and Acceptable Use Policy.

## Durability warning

We do NOT guarantee data durability. Keep your own backups of anything you cannot
lose, especially during beta.

## Links

- Terms of Service: https://storkhost.cloud/tos
- Service Level Agreement: https://storkhost.cloud/sla
- Privacy Policy: https://storkhost.cloud/privacy
- Status page: https://storkhost.cloud/status
- Pricing: https://storkhost.cloud/pricing
- This file: https://storkhost.cloud/llms.txt  (auto-generated, updated each ship)

## Status

Beta. Operated by **Storksoft**, an independent operator. Contact:
`support@storkhost.cloud` (support/disputes), `abuse@storkhost.cloud` (abuse),
`privacy@storkhost.cloud` (privacy). SLA is best-effort with no service credits
during beta. Provided as-is.