# InstaServer

A free, open-source, self-hosted alternative to InstaPods, Vercel, and other centralized deploy platforms.

InstaServer is an [MCP server](https://modelcontextprotocol.io) that gives an AI agent (Claude Code, or any MCP client) the same kind of tools InstaPods offers — `deploy_pod`, `exec_command`, `get_logs`, `read_file`/`write_file`, and so on — except every "pod" is a real Docker container running **on your own machine**, with a public HTTPS URL from a free [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). No account, no signup, no payment method, no per-deploy billing, no platform-imposed rate limit.

## Why this exists

Centralized platforms (Vercel, Netlify, InstaPods, etc.) are convenient until their free/hobby tier throttles you — a burst of a dozen pushes in an hour can trip a build-rate limit and silently freeze your production deploys for days, with no obvious signal that it happened. InstaServer trades platform convenience for **owning the whole stack**: your machine, your Docker engine, your uptime, no ceiling.

Trade-off, stated plainly: your machine has to be on for the pod to be reachable, and the free Cloudflare quick tunnel is explicitly best-effort (Cloudflare's own words: "no uptime guarantee"). This is the right tool for local development, demos, side projects, and internal tools — not a drop-in replacement for production hosting of a business-critical site with an SLA.

## Requirements

- Node.js 20+
- [colima](https://github.com/abiosoft/colima) (or Docker Desktop) — provides the Docker engine
- [cloudflared](https://github.com/cloudflare/cloudflared) — provides free quick tunnels

```bash
brew install colima docker cloudflared
colima start --cpu 2 --memory 4 --disk 20
```

## Install

```bash
git clone <this repo> instaserver
cd instaserver
npm install
npm run build
```

## Register it as an MCP server

With the Claude Code CLI:

```bash
claude mcp add instaserver -- node /absolute/path/to/instaserver/dist/index.js
```

Or add it manually to your MCP client's config (e.g. `~/.claude.json` under `mcpServers`, or a project's `.mcp.json`):

```json
{
  "mcpServers": {
    "instaserver": {
      "command": "node",
      "args": ["/absolute/path/to/instaserver/dist/index.js"]
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `list_presets` | List runtime presets (`static`, `nodejs`, `python`) |
| `create_pod` | Register a new pod (volume only, nothing running yet) |
| `deploy_pod` | **Main tool.** Create-if-missing, upload files, install deps, (re)start, open a public URL, verify it answers |
| `list_pods` | List all pods and status |
| `get_pod` | Get one pod's details/URL/status |
| `manage_pod` | `start` / `stop` / `restart` / `reload` |
| `delete_pod` | Remove a pod's container, volume, and tunnel |
| `exec_command` | Run a shell command inside a pod |
| `get_logs` | Recent stdout/stderr from the pod's app |
| `list_files` / `read_file` / `write_file` | Inspect and edit files without a full redeploy |

## Presets

- **static** — `nginx:alpine`, serves the uploaded files as-is. Entry: `index.html`.
- **nodejs** — `node:20-alpine`, runs `npm install` if `package.json` is present, then `node <entry>`. Entry: `server.js` / `index.js` / `app.js`. `PORT=8080` is set for you.
- **python** — `python:3.12-alpine`, runs `pip install -r requirements.txt` if present, then `python <entry>`. Entry: `main.py` / `app.py` / `server.py`. `PORT=8080` is set for you.

## How it works

Each pod is a named Docker volume (persistent app storage) + a named container built from the preset's image, with the volume mounted at the app root and the container's port published to a free host port. `deploy_pod` stages your files locally, `docker cp`s them into the container, and boots it with `sh -c "<install> && exec <start>"`. A [cloudflared quick tunnel](https://github.com/cloudflare/cloudflared) is opened against the host port to get a public `https://*.trycloudflare.com` URL — reachability is verified before the URL is handed back, retrying with a fresh hostname up to 3 times if Cloudflare's registration doesn't come up cleanly (this happens occasionally; it's a known characteristic of the free tier, not a bug).

Pod state lives in `~/.instapod-free/state.json` so the MCP server can restart without losing track of what's running.

## Limitations (read before relying on this)

- Your machine needs to be on and awake for pods to be reachable.
- Free Cloudflare quick tunnels are best-effort — no SLA, hostnames can occasionally need a retry.
- No built-in TLS cert management beyond what the tunnel provides, no custom domains, no multi-region.
- Presets are minimal by design (three runtimes). Extending `src/presets.ts` is straightforward if you need another.

## License

MIT — see [LICENSE](./LICENSE).