# TinyCompute

> Multi-provider compute marketplace via micropayments. No accounts. No API keys.

Source: https://github.com/stuxf/tinycompute

## Setup

Install the tempo CLI (handles MPP payments automatically):
```
mkdir -p "$HOME/.local/bin" && curl -fsSL https://tempo.xyz/install -o /tmp/tempo_install.sh && TEMPO_BIN_DIR="$HOME/.local/bin" bash /tmp/tempo_install.sh
export PATH="$HOME/.local/bin:$PATH"
tempo wallet login
```

## Quick Start

Create a machine ($0.10):
```
tempo request -t -X POST --json '{"name":"my-server","region":"sjc","config":{"image":"ubuntu:latest","init":{"cmd":["sleep","infinity"]},"guest":{"cpu_kind":"shared","cpus":1,"memory_mb":512}}}' https://tinycompute.dev/api/machines
```
The response includes `connection.ips` and `connection.ports` for connecting to the machine.

Create a game server (e.g., Minecraft — needs 4GB RAM for Paper world gen):
```
tempo request -t -X POST --json '{"name":"mc-server","ttl_minutes":60,"region":"sjc","config":{"image":"itzg/minecraft-server:latest","env":{"EULA":"TRUE","TYPE":"PAPER","MEMORY":"3G"},"guest":{"cpu_kind":"shared","cpus":2,"memory_mb":4096},"services":[{"protocol":"tcp","internal_port":25565,"ports":[{"port":25565}]}]}}' https://tinycompute.dev/api/machines
```
Connect via the IP from `connection.ips` on port 25565. No TLS handlers for raw TCP.
Note: Paper server takes 2-3 minutes to download JARs and generate the world. Check readiness with `mc-health` via exec.

Run a command ($0.01):
```
tempo request -t -X POST --json '{"command":["ls","-la"]}' https://tinycompute.dev/api/machines/{id}/exec
```

Stop ($0.001):
```
tempo request -t -X POST https://tinycompute.dev/api/machines/{id}/stop
```

Destroy ($0.001):
```
tempo request -t -X DELETE https://tinycompute.dev/api/machines/{id}
```

## Important

- Use `init.cmd: ["sleep","infinity"]` for base images like ubuntu/debian — without it the container exits immediately.
- Images with built-in servers (nginx, postgres, node apps) don't need init.cmd.
- All costs are in USDC, paid automatically via MPP through the tempo CLI.
- The create response includes a `connection` object with public IPs and ports.
- Machines run on the `mpp-compute` Fly app which has a shared IPv4. Use the IP from `GET /api/apps/mpp-compute/ips`.

## Service Configuration (TCP/UDP ports)

To expose a port (e.g., a game server, database, web server), add `services` to your config:

Raw TCP (game servers, databases — NO TLS):
```json
"services": [{"protocol": "tcp", "internal_port": 25565, "ports": [{"port": 25565}]}]
```

HTTP/HTTPS (web apps):
```json
"services": [{"protocol": "tcp", "internal_port": 8080, "ports": [{"port": 443, "handlers": ["tls", "http"]}, {"port": 80, "handlers": ["http"]}]}]
```

Do NOT add `"handlers": ["tls"]` for raw TCP protocols like Minecraft, PostgreSQL, Redis, etc. Only use handlers for HTTP traffic.

## Resource Sizing Guide

| Workload | CPUs | RAM | Notes |
|----------|------|-----|-------|
| Simple script / sleep | 1 | 256MB | Minimal |
| Web server (nginx, node) | 1 | 512MB | |
| Database (postgres, redis) | 1-2 | 1-2GB | |
| Minecraft (Paper) | 2 | 4GB | Paper needs 3G+ for world gen |
| Heavy build / compile | 2-4 | 4-8GB | |

Max per machine: 8 CPUs, 8GB RAM (shared), or 4GB (performance).

## Auto-Stop (TTL)

Add `"ttl_minutes": 60` to your create request. The machine will be auto-stopped after the specified time (max 1440 min / 24 hours). TTL is stored as metadata — it does NOT override the Docker image's entrypoint. Works with any image.

```
tempo request -t -X POST --json '{"name":"temp-server","ttl_minutes":10,"region":"sjc","config":{"image":"ubuntu:latest","init":{"cmd":["sleep","infinity"]},"guest":{"cpu_kind":"shared","cpus":1,"memory_mb":512}}}' https://tinycompute.dev/api/machines
```

## Providers

- **Fly.io**: Firecracker microVMs, 35+ regions, sub-second boot
- **DigitalOcean**: Droplets (VMs)
- **Vercel**: Projects, deployments, domains, DNS
- **Upstash**: Redis-compatible KV databases

## Pricing

Compute pricing scales with machine size. Prices shown in the 402 challenge.

### Fly.io Machines (dynamic)

| Size | Setup fee | Per-minute rate | Per-hour |
|------|-----------|----------------|----------|
| shared 1cpu / 256MB | $0.10 | $0.004/min | $0.24/hr |
| shared 1cpu / 512MB | $0.11 | $0.005/min | $0.30/hr |
| shared 2cpu / 2GB | $0.17 | $0.014/min | $0.84/hr |
| shared 2cpu / 4GB | $0.21 | $0.022/min | $1.32/hr |
| shared 4cpu / 8GB | $0.37 | $0.044/min | $2.64/hr |
| perf 2cpu / 4GB | $0.21 | $0.028/min | $1.68/hr |

### DigitalOcean Droplets (dynamic)

| Size | Setup fee | Per-minute rate | Per-hour |
|------|-----------|----------------|----------|
| s-1vcpu-512mb | $0.15 | $0.005/min | $0.30/hr |
| s-1vcpu-1gb | $0.16 | $0.006/min | $0.36/hr |
| s-2vcpu-4gb | $0.24 | $0.014/min | $0.84/hr |
| s-4vcpu-8gb | $0.34 | $0.024/min | $1.44/hr |

### Other Operations (fixed)

| Action | Cost |
|--------|------|
| Execute command | $0.01 |
| Create volume | $0.05 |
| Extend volume | $0.05 |
| Allocate IP | $0.01 |
| Create Vercel project / deployment | $0.10 |
| Create KV database | $0.05 |
| Add DNS record / env var / project domain | $0.01 |
| Check domain availability | $0.001 |
| Buy / renew domain | Market price |
| KV get / set / del / keys | $0.001 |
| Get, list, stop, destroy, etc. | $0.001 |

## API Reference

Base URL: https://tinycompute.dev

### Fly.io Machines

POST /api/machines — Create machine ($0.10)
  Body: {"name":"string","region":"sjc","config":{"image":"string","init":{"cmd":["sleep","infinity"]},"guest":{"cpu_kind":"shared","cpus":1,"memory_mb":256},"env":{"KEY":"val"},"services":[{"protocol":"tcp","internal_port":8080,"ports":[{"port":443,"handlers":["tls","http"]}]}]}}
  Regions: ams, arn, atl, bog, bom, bos, cdg, den, dfw, ewr, eze, fra, gdl, gig, gru, hkg, iad, jnb, lax, lhr, mad, mia, nrt, ord, otp, phx, qro, scl, sea, sin, sjc, syd, waw, yul, yyz

GET /api/machines — List my machines ($0.001)
GET /api/machines/:id — Get machine ($0.001)
POST /api/machines/:id/start — Start machine (session $0.005/min)
POST /api/machines/:id/stop — Stop machine ($0.001)
POST /api/machines/:id/restart — Restart machine (session $0.005/min)
DELETE /api/machines/:id — Destroy machine ($0.001)
POST /api/machines/:id/exec — Execute command ($0.01)
  Body: {"command":["ls","-la","/"],"timeout":30}
POST /api/machines/:id/wait — Wait for state ($0.001)
  Query: ?state=started&timeout=60
GET /api/machines/:id/events — Machine events ($0.001)
POST /api/machines/:id/suspend — Suspend machine ($0.001)
GET /api/machines/:id/ps — List processes ($0.001)
GET /api/machines/:id/billing — Billing info ($0.001)

### Fly.io Volumes

POST /api/volumes — Create volume ($0.05)
  Body: {"name":"my_data","region":"sjc","size_gb":1}
GET /api/volumes — List volumes ($0.001)
GET /api/volumes/:id — Get volume ($0.001)
DELETE /api/volumes/:id — Delete volume ($0.001)
PUT /api/volumes/:id/extend — Extend volume ($0.05)
  Body: {"size_gb":5}

### Fly.io Apps

POST /api/apps — Create app ($0.001)
DELETE /api/apps/:name — Delete app ($0.001)
GET /api/apps/:name/ips — List IPs (free)
POST /api/apps/:name/ips — Allocate IP ($0.01)

### DigitalOcean Droplets

POST /api/do/droplets — Create droplet ($0.10)
  Body: {"name":"my-droplet","region":"nyc1","size":"s-1vcpu-1gb","image":"ubuntu-24-04-x64"}
  Sizes: s-1vcpu-512mb-10gb, s-1vcpu-1gb, s-1vcpu-2gb, s-2vcpu-2gb, s-2vcpu-4gb, s-4vcpu-8gb
  Regions: nyc1, nyc3, sfo3, ams3, sgp1, lon1, fra1, tor1, blr1, syd1
GET /api/do/droplets — List droplets ($0.001)
GET /api/do/droplets/:id — Get droplet ($0.001)
POST /api/do/droplets/:id/start — Power on (session $0.005/min)
POST /api/do/droplets/:id/stop — Power off ($0.001)
DELETE /api/do/droplets/:id — Destroy ($0.001)

### Vercel Projects

POST /api/vercel/projects — Create project ($0.10)
GET /api/vercel/projects — List projects ($0.001)
GET /api/vercel/projects/:id — Get project ($0.001)
DELETE /api/vercel/projects/:id — Delete project ($0.001)
POST /api/vercel/projects/:id/env — Add env var ($0.01)
  Body: {"key":"NODE_ENV","value":"production","target":["production","preview"]}
POST /api/vercel/projects/:id/domains — Add domain to project ($0.01)
  Body: {"domain":"example.com"}

### Vercel Deployments

POST /api/vercel/deployments — Create deployment ($0.10)
  Body: {"name":"my-app","project":"prj_xxx","target":"production"}
GET /api/vercel/deployments — List deployments ($0.001)
  Query: ?projectId=xxx&limit=20&state=READY&target=production

### Vercel Domains

POST /api/vercel/domains/check — Check domain availability ($0.001)
POST /api/vercel/domains/buy — Buy domain (market price)
GET /api/vercel/domains — List domains ($0.001)
GET /api/vercel/domains/:name — Get domain info ($0.001)
DELETE /api/vercel/domains/:name — Get auth code for transfer ($0.001)
GET /api/vercel/domains/:name/price — Get domain price ($0.001)
POST /api/vercel/domains/:name/renew — Renew domain (market price)
GET /api/vercel/domains/:name/dns — List DNS records ($0.001)
POST /api/vercel/domains/:name/dns — Add DNS record ($0.01)
  Body: {"type":"A","name":"@","value":"1.2.3.4"}
DELETE /api/vercel/domains/:name/dns/:id — Delete DNS record ($0.001)

### Upstash KV

POST /api/kv/databases — Create KV database ($0.05)
  Body: {"name":"my-cache","region":"us-east-1"}
GET /api/kv/databases — List databases ($0.001)
DELETE /api/kv/databases/:id — Delete database ($0.001)
POST /api/kv/:db/set — Set key ($0.001)
  Body: {"key":"mykey","value":"myval","ex":3600}
POST /api/kv/:db/get — Get key ($0.001)
  Body: {"key":"mykey"}
POST /api/kv/:db/del — Delete key ($0.001)
  Body: {"key":"mykey"}
POST /api/kv/:db/keys — List keys ($0.001)
  Body: {"pattern":"user:*"}

### System

GET /health — Health check (free, no auth)
GET /llms.txt — This file (free, no auth)