Docs
Quickstart: from account to live app
You need a GitHub account and a coding agent that supports MCP. The whole thing takes a few minutes.
1. Create an account
Open the portal and sign in with GitHub. The first sign-in creates your account on the free plan (2 apps) and shows your first API key – once. Copy it.
You can create more keys under API keys, one per agent, and revoke them separately.
2. Connect your agent
Shipholm is a remote MCP server:
URL: https://api.shipholm.com/mcp
Header: Authorization: Bearer <your API key>
In Claude Code that is one command:
claude mcp add --transport http shipholm https://api.shipholm.com/mcp \
--header "Authorization: Bearer <your API key>"
Configuration for Codex, Cursor, VS Code, opencode, Hermes, Windsurf and Claude Desktop: Connect an agent.
3. Ask your agent to publish
Use the Shipholm MCP server. Call get_platform_info first, then publish
https://github.com/<you>/<repo> as an app and tell me its URL when it is ready.
The agent calls create_app, waits with app_status until
ready is true (the first build takes a few minutes) and gives you the address:
https://<app>.shipholm.dev.
From then on every push to the branch is deployed automatically. Nobody calls Shipholm again for a new version.
Private repositories
Public repositories work at once. For private ones – and instant builds on push – install the
Shipholm GitHub App: your agent calls connect_github and gives you a link, or use
GitHub in the portal. You choose which repositories it may read.
The contract every app follows
| Topic | Rule |
|---|---|
| Port | Listen on $PORT (default 8080) |
| Health | Answer HTTP 200 on / (or the health_path you set) |
| User | The container runs as uid 10001, never as root |
| Filesystem | Read-only except /tmp; keep data in the database |
| Database | DATABASE_URL points at the app's own Postgres (unless created with database=false) |
| Build | Your Dockerfile if there is one; otherwise detected (Node, Vite, Next.js, Python, Go, static sites …) |
| Settings | env values are stored in plain text – do not put secrets there |
The tools your agent gets
| Tool | What it does |
|---|---|
get_platform_info | Your account, the contract above, the GitHub sources you may build from |
create_app · update_app · delete_app | Create an app from a repository or an image, change it, remove it |
list_apps · get_app | What you have and how it is set up |
app_status | Ready or not, with hints about what to do when it is not |
app_logs | The app's output, also from the previous crash |
build_log · rebuild_app | Why the last build failed (the end of its log), and build again |
restart_app | Restart the app's pods (data on the disk and in the database is kept) |
app_history · rollback_app | The images the app has run, and going back to one of them |
delete_account | Close the account and delete everything in it (also in the portal: Plan) |
add_domain · verify_domain · remove_domain | Your own domain |
connect_github | A link for you to connect a GitHub account or organisation |
get_account | Your plan, its limits and what you use |
A static site or a game without a build step
Add this Dockerfile to the repository and ask the agent to create the app with
database=false and scale_to_zero=true:
FROM python:3.13-slim
ENV PYTHONDONTWRITEBYTECODE=1 PORT=8080
WORKDIR /site
COPY . .
USER 10001
CMD ["sh", "-c", "exec python3 -m http.server \"$PORT\" --bind 0.0.0.0"]
When something is wrong
app_statusreturnshintsin plain language: still building, image cannot be pulled, crashing, and so on.app_logsshows what the app printed. In the portal: Apps → Logs.- A failed build shows in
app_status;build_loghas the end of the build output. The app keeps running the last good build. A failing commit is tried three times – push a fix, or callrebuild_appto build again. - A new version broke the app:
rollback_appgoes back to the previous image at once, then fix and push. The database and the disk are not rolled back. - “The free plan allows 2 apps” – delete one, or wait for the paid plan.