# ShipDapp

> ShipDapp is a decentralized app hosting platform. Deploy any Dockerized app to Akash Network with Solana community-funded vaults and AI agent deployment via Model Context Protocol (MCP).

## What is ShipDapp?

ShipDapp lets developers deploy Dockerized web applications to the Akash Network (decentralized cloud) with Solana-based community funding. AI coding assistants connect via MCP to scaffold, build, deploy, and monitor apps without leaving the editor.

## Key facts

- **Platform**: https://shipdapp.com
- **API / MCP**: https://api.shipdapp.com
- **GitHub**: https://github.com/yash1ts/shipdapp
- **Hosting network**: Akash Network (devnet for MCP deploys)
- **Payments / vaults**: Solana
- **MCP version**: 0.2.0

## Who should use ShipDapp?

- Developers who want censorship-resistant, community-funded hosting
- AI agent builders using Cursor, Claude Code, or Windsurf with MCP
- Teams deploying Dockerized apps without centralized cloud lock-in
- Farcaster builders shipping mini-apps via https://shipdapp.com/apps

## Documentation

- [Full MCP reference](https://api.shipdapp.com/llm-full.txt): Every tool, parameter, workflow, guardrail, and config snippet
- [API keys](https://shipdapp.com/account/keys): Generate `shipdapp_sk_*` keys for Cursor, Claude, and other MCP clients
- [Example agent](https://github.com/yash1ts/shipdapp/tree/main/examples/x-agency-agent): Reference local-first deploy agent
- [App Store](https://shipdapp.com/store): Browse and fund community deployments
- [Vibe Terminal](https://shipdapp.com/terminal): Browser-based AI coding environment

## Connect MCP

- MCP SSE URL: `https://api.shipdapp.com/api/mcp/sse`
- Auth: `Authorization: Bearer shipdapp_sk_...` in MCP client **headers** (never in chat or tool arguments)
- Alternative auth: `get_auth_challenge` + `authenticate` (Sign-In With Solana, local wallet)

## Recommended workflow

Source deployment:

1. `list_templates` with `includeFiles=true` → write scaffold to disk
2. Develop and test locally (`npm run dev`, `npm run build`)
3. `list_template_files` + `validate_upload` — confirm entry + local imports resolve (any component filename is fine)
4. `deploy_app` with `templateId` + complete local `files` map (omit `package-lock.json`; default `mergeMode=strict`). Apps are unlisted by default — pass `listOnStore=true` to appear on the App Store.
5. Poll `get_app_status(deploymentId)` until `ACTIVE` **and** `httpReady=true` → share `proxyUri` (`ACTIVE` alone can still be HTTP 503)
6. Optional: `set_app_listing({ deploymentId, listed: true })` to list later

Prebuilt image deployment:

1. Build and push a public Docker/OCI image yourself
2. `deploy_image` with `appName`, `dockerImage`, and `port` (optional `listOnStore=true`)
3. Poll `get_app_status(deploymentId)` until `ACTIVE` and `httpReady=true` → share `proxyUri`

## Tools (summary)

| Tool | When to use |
|------|-------------|
| `get_auth_challenge` | SIWS wallet auth (skip if using API key in headers) |
| `authenticate` | Complete SIWS after signing challenge locally |
| `get_usage_limits` | After guardrail block or before planning multiple deploys |
| `list_templates` | Bootstrap new app or get `templateId` for deploy |
| `list_template_files` | Exact required vs optional paths before upload |
| `validate_upload` | Dry-run: missing files, garbage placeholders, template fills |
| `deploy_app` | Source upload — Cloud Build + registered BUILDING deployment |
| `deploy_image` | Prebuilt image deploy — no source upload, no Cloud Build |
| `build_image` | Build only, no deployment (verify build before deploy) |
| `get_build_status` | Optional Cloud Build debug (prefer `get_app_status` after deploy) |
| `update_app` | Push new code to an existing deployment |
| `get_app_status` | Primary poll — returns `proxyUri`, `httpReady`, `readiness` |
| `list_apps` | List deployments and find `deploymentId` |
| `set_app_listing` | List or unlist an app on the public App Store |
| `get_logs` | Debug build failures or runtime crashes (inline build log tail on FAILURE) |
| `close_app` | Permanently tear down a deployment |

## FAQ

**What is ShipDapp?**
ShipDapp is a decentralized application hosting platform. Deploy Dockerized apps to Akash Network and manage them with Solana community-funded vaults.

**How does MCP integration work?**
Add the MCP endpoint to your AI editor config, authenticate with an API key or Solana wallet, and your agent can scaffold, build, deploy, and monitor apps on Akash devnet.

**Do I need a Solana wallet?**
Not for Vibe Terminal coding. A wallet is required for deploying apps, funding vaults, or SIWS agent auth.

**Where are apps hosted?**
Apps run as Docker containers on Akash Network — a global P2P decentralized cloud with censorship resistance and lower cost than centralized providers.

## Optional REST (no MCP auth)

- `GET https://api.shipdapp.com/api/templates` — list templates
- `GET https://api.shipdapp.com/api/templates/:id?includeFiles=true&appName=my-app` — download scaffold

## Rules for agents

- Never paste API keys into chat, tool arguments, or user-visible output
- Do not call `deploy_app` until local `npm run build` succeeds
- Call `validate_upload` — strict mode requires `package.json` + `index.html` and that the HTML entry's local imports resolve; it never injects starter Tailwind/PostCSS/React files (upload is used as-is)
- Omit `package-lock.json` from MCP uploads — Cloud Build runs `npm install`
- Poll until `httpReady=true`, not just `ACTIVE`
- Use `deploy_image` when you already have a public container image URI
- Do not retry the same blocked action in a loop — call `get_usage_limits` first
- Use `update_app` for changes to existing apps, not `deploy_app`
- Use `close_app` only when permanently shutting down an app
- REST `/api/deployments` rejects MCP API keys — use MCP tools, not REST, for agent deploys