# Openship

> Openship is an open-source platform to build, deploy, and run apps on your own servers or Openship Cloud, managed from a dashboard, REST API, CLI, and MCP.

## Docs
- [Introduction](https://openship.io/docs.md): What Openship is, who it's for, and the three places you can run your apps — your own machine, your own server, or the cloud.
- [MCP](https://openship.io/docs/mcp.md): Let AI clients like Claude drive your Openship instance as tools, over the Model Context Protocol.
- [Desktop app & local data](https://openship.io/docs/troubleshooting/desktop-data.md): Fix desktop and self-hosted startup problems — the database lock, "can't reach the server", a stuck update — and find where your local data lives and how to recover it.
- [Host control channel](https://openship.io/docs/troubleshooting/host-channel.md): "This operation targets the HOST machine, but no host channel is configured" — what the host channel is, why the rest of the install looks healthy, and the repair for each install shape.
- [Common errors](https://openship.io/docs/troubleshooting/common-errors.md): The API error codes and messages you'll actually hit — what each one means, and how to fix it.
- [GitHub connection & repos](https://openship.io/docs/troubleshooting/github.md): Fix an expired or unauthorized GitHub connection, a private repo that won't import, a public repo that should just work, and auto-deploy webhooks that never fire.
- [Troubleshooting](https://openship.io/docs/troubleshooting.md): Where Openship shows you what went wrong — the build screen, the Logs tab, and the CLI — and how to read an error before you try to fix it.
- [Domains, DNS & SSL](https://openship.io/docs/troubleshooting/domains-ssl.md): Fix a custom domain that won't verify, DNS that hasn't propagated, an SSL certificate stuck on Provisioning, and the external-ingress (TXT-only) case.
- [Deployment & build failures](https://openship.io/docs/troubleshooting/deployments.md): The build went red — here's how to read the failure and fix the usual causes, from a wrong build command to a compose deploy that needs a decision.
- [Servers & SSH](https://openship.io/docs/troubleshooting/servers-ssh.md): Fix a server that won't connect over SSH, a component that won't install or reports unhealthy, missing Docker, and port-forward tunnels that won't start.
- [Mail API](https://openship.io/docs/api/mail.md): Install and adopt an iRedMail stack over SSH, run the mail admin panel (domains, mailboxes, stats, backups, DNS, components), and deploy webmail.
- [Permissions API](https://openship.io/docs/api/permissions.md): Manage team organizations, per-resource grants, and invitations with pending grants.
- [Migration API](https://openship.io/docs/api/migration.md): Scan a server's existing Docker deployment and adopt the discovered services as an Openship project.
- [Services API](https://openship.io/docs/api/services.md): Manage the services inside a project — compose services and monorepo sub-apps — including CRUD, sync from compose, container actions, drift resolution, and env vars.
- [Audit API](https://openship.io/docs/api/audit.md): Read the append-only audit log for your organization — who did what, when — with cursor or page pagination and filters.
- [Health API](https://openship.io/docs/api/health.md): Public liveness and deployment-info probes for load balancers, Docker health checks, and clients discovering how an instance is configured.
- [Backup destinations API](https://openship.io/docs/api/backup-destinations.md): Manage the storage targets (S3-compatible, SFTP, local, or another Openship server) that backups are written to, and run a connectivity preflight.
- [Images API](https://openship.io/docs/api/images.md): List the build-image catalog — the ready-made service images (databases, caches, and more) you can pick when adding a service.
- [Projects API](https://openship.io/docs/api/projects.md): Create and configure projects, link a git repo, manage env vars and resources, read logs, deploy an uploaded folder, and transfer projects to and from Openship Cloud.
- [Backups API](https://openship.io/docs/api/backups.md): Schedule backup policies, run and inspect backups, stage and apply restores, and trigger backups by webhook.
- [Service terminal API](https://openship.io/docs/api/service-terminal.md): Open an interactive shell into a running service container over a WebSocket, authenticated by a one-shot ticket.
- [Domains API](https://openship.io/docs/api/domains.md): Attach custom domains to a project, preview and verify DNS, and manage SSL certificates.
- [Billing API](https://openship.io/docs/api/billing.md): Read published plans without auth, then manage a subscription, usage, credit top-ups, and the Stripe portal on Openship Cloud. Self-hosted Openship has no billing.
- [Auth API](https://openship.io/docs/api/auth.md): The Better Auth wrapper plus the desktop session-bootstrap and cloud sign-in handoff, mounted under /api/auth.
- [GitHub API](https://openship.io/docs/api/github.md): Connect a GitHub account or App, browse repos, branches and files, and manage push webhooks.
- [Tokens API](https://openship.io/docs/api/tokens.md): Mint, list, and revoke personal access tokens, and manage the MCP clients authorized against your account.
- [Webhooks API](https://openship.io/docs/api/webhooks.md): The unified inbound webhook endpoint that verifies provider signatures and turns a GitHub push into an auto-deploy.
- [Analytics API](https://openship.io/docs/api/analytics.md): Read request traffic, deployment stats, and container resource usage for a project or the whole org, plus per-server edge analytics.
- [API overview](https://openship.io/docs/api.md): The Openship HTTP API — base URL, authentication, permissions, rate limits, and the standard JSON error shape.
- [Settings API](https://openship.io/docs/api/settings.md): Read and update your Openship workspace preferences — build mode, deploy defaults, and git clone credentials.
- [MCP API](https://openship.io/docs/api/mcp.md): The Streamable-HTTP JSON-RPC endpoint that exposes Openship's API to AI clients as tools, re-authenticating every call.
- [Apps API](https://openship.io/docs/api/apps.md): Browse the one-click app catalog, install an app as a project, manage per-organization custom apps, and read an installed app's curated settings and resolved connection details.
- [Deployments API](https://openship.io/docs/api/deployments.md): Trigger builds, deploy from git or an uploaded folder, then inspect, redeploy, roll back, and manage the lifecycle of a project's releases.
- [Terminal API](https://openship.io/docs/api/terminal.md): Open an interactive SSH shell to a managed server over a WebSocket, authenticated by a single-use handshake ticket.
- [DNS API](https://openship.io/docs/api/dns.md): Connect a DNS provider, preview each DNS change, and apply a domain's records without copying them by hand.
- [System API](https://openship.io/docs/api/system.md): Self-hosted instance administration — onboarding, SSH servers, component install, tunnels, filesystem browse, team-mode migration, and whole-instance data transfer.
- [Notifications API](https://openship.io/docs/api/notifications.md): Manage delivery channels, per-event subscriptions, org defaults, and the in-app alert feed.
- [Cloud API](https://openship.io/docs/api/cloud.md): Connect a self-hosted instance to Openship Cloud, and the cloud control-plane endpoints (handoff, edge proxy, pages, subgraph transfer, GitHub App proxy) that back it.
- [Your first deployment](https://openship.io/docs/getting-started/first-deployment.md): A gentle, screen-by-screen walkthrough of putting one real GitHub app online with Openship — and what "live" actually looks like.
- [Installation](https://openship.io/docs/getting-started/installation.md): Every way to get Openship running — the one-line install script, the npm CLI, the desktop app, or a Docker Compose stack.
- [Quickstart](https://openship.io/docs/getting-started/quickstart.md): The fastest path from a fresh install to a live app — start Openship, open the dashboard, and deploy one thing.
- [Core concepts](https://openship.io/docs/getting-started/core-concepts.md): The plain-language vocabulary the rest of the docs use — organizations, projects, deployments, services, servers, domains, environments, and runtimes.
- [Projects](https://openship.io/docs/dashboard/projects.md): The Projects list and the nine-tab project detail screen — where you find every app you've deployed and manage its domains, deploys, config, logs, and backups.
- [Backups](https://openship.io/docs/dashboard/backups.md): The Backups page is where you register storage targets — S3 buckets, SFTP hosts, an existing server, or local disk — that your projects back up to.
- [Billing](https://openship.io/docs/dashboard/billing.md): The Billing area (Openship Cloud only) shows your plan, usage, and invoices. Self-hosted Openship has no billing.
- [The dashboard](https://openship.io/docs/dashboard.md): A tour of the Openship dashboard — the sidebar that navigates everything, the home overview, and a map to each area.
- [Settings](https://openship.io/docs/dashboard/settings.md): The Settings screen — GitHub connection, deploy defaults, tokens, MCP, team, notifications, audit log, cloud, and instance controls, one tab at a time.
- [Servers](https://openship.io/docs/dashboard/servers.md): Add your own servers over SSH, let Openship install what a deployment needs, and manage each server's health, rate limiting, port forwarding, and a live terminal.
- [New Project (Library)](https://openship.io/docs/dashboard/library.md): The source picker that starts every deployment — upload a folder, import a GitHub repo, paste a Git URL, pick a template, or adopt an existing server.
- [The deploy wizard](https://openship.io/docs/dashboard/deploy-wizard.md): The screen where you choose where your app runs, review the detected build, and watch it go live.
- [Emails](https://openship.io/docs/dashboard/emails.md): Run your own mail server from the dashboard — provision or adopt a server, walk the setup wizard, and manage domains and mailboxes from the ten-tab admin panel.
- [Projects, services & domains](https://openship.io/docs/cli/projects.md): Link a directory and manage projects, compose services, and custom domains from the terminal with openship init, project, service, and domain.
- [Running & updating](https://openship.io/docs/cli/run.md): Start, stop, update, and health-check the Openship server itself from the terminal — up, stop, reset-admin-password, update, install, open, status, and doctor.
- [Access & the raw API](https://openship.io/docs/cli/access.md): Log in, switch between instances with contexts, manage personal access tokens, and call any API route directly with openship api.
- [Deploying](https://openship.io/docs/cli/deploy.md): Ship a project, manage its deployments, and follow the logs — the full deploy loop from the terminal.
- [Self-host infrastructure](https://openship.io/docs/cli/self-host.md): CLI reference for the server, system, mail, and backup commands that operate an Openship instance you run yourself.
- [CLI overview](https://openship.io/docs/cli.md): Install the openship CLI, log in with a token, understand connection contexts, and find every command at a glance.
- [Edge & monitoring](https://openship.io/docs/cli/edge.md): Manage the OpenResty edge from the terminal — install and serve :80/:443, take over an existing reverse proxy and import its sites, route domains, apply per-route rules, and read traffic, analytics, and request logs.
- [Architecture overview](https://openship.io/docs/architecture/overview.md): A high-level map of how Openship fits together — the interfaces you drive, the API that runs everything, the platform adapters, and the shared packages.
- [Modules overview](https://openship.io/docs/architecture/modules-overview.md): A tour of the backend modules that make up the Openship API — what each one owns, grouped by job, with a link to its reference page.
- [Cloud as source](https://openship.io/docs/architecture/cloud-as-source.md): Cloud projects are owned by Openship Cloud; your self-hosted instance is a gateway in front of it — plus how projects promote up and come back home.
- [Runtime model](https://openship.io/docs/architecture/runtime-model.md): The three places an app can run — this machine, your own server over SSH, or Openship Cloud — and how a build and deploy flow in each.
- [Data ownership](https://openship.io/docs/architecture/data-ownership.md): Where your data lives when you self-host, how to export and import everything so there's no lock-in, and how the desktop app guards the local data directory.
- [App catalog JSON](https://openship.io/docs/reference/app-catalog.md): The complete field reference for an Openship App definition — the JSON that turns a set of containers into a one-click install, with generated secrets, a curated settings form, and a connection card.
- [openship.json](https://openship.io/docs/reference/openship-json.md): The declarative deploy config for Openship — like vercel.json or railway.toml. Declare framework, build, runtime, env, domains, routes, resources, services and monorepo layout, and Openship deploys the same way every time.
- [Permissions & roles](https://openship.io/docs/security/permissions.md): How Openship decides who can do what — organizations, the four roles, and per-resource grants, all enforced by one permission plane.
- [Authentication](https://openship.io/docs/security/auth.md): How you prove who you are to Openship — session cookies, personal access tokens, MCP OAuth, and desktop loopback mode.
- [Cloud boundary](https://openship.io/docs/security/cloud-boundary.md): How a self-hosted instance talks to Openship Cloud without leaking local identity — proxied requests carry the owner's cloud session and nothing else.
- [Isolation](https://openship.io/docs/security/isolation.md): How Openship keeps deployments and projects apart — separate containers, per-project networks and volumes, and enforced resource limits.
- [Migrate from Coolify, Dokploy, or Dokku](https://openship.io/docs/guides/migrate-from-coolify-dokploy-dokku.md): Move an existing self-hosted server onto Openship without redeploying from scratch — Openship scans your running Docker containers and adopts them in place, with a zero-downtime path and server-to-server moves.
- [Updating Openship](https://openship.io/docs/guides/updating.md): Keep your Openship up to date — the one-click desktop updater, the CLI update command, and how the always-on service picks up a new release.
- [Auto-deploy on push](https://openship.io/docs/guides/auto-deploy.md): Make Openship rebuild and ship your app automatically every time you push to GitHub — from the dashboard or the terminal.
- [Add an app](https://openship.io/docs/guides/add-an-app.md): Write the catalog JSON that makes a one-click Openship app, built up field by field from a bare service to a complete submission — plus how to ship it as a pull request or upload it privately to your own organization.
- [Connect your own server](https://openship.io/docs/guides/custom-servers.md): Add one of your own machines over SSH and let Openship install everything it needs to run your apps.
- [Database migrations & stateful safety](https://openship.io/docs/guides/database-migrations.md): Safely back up and migrate a persistent database (MySQL/Postgres) volume around a deploy — using Openship's pre-deploy backup trigger and post-deploy jobs.
- [Connect to Cloud & migrate](https://openship.io/docs/guides/cloud-connect-migration.md): Link the copy of Openship you run yourself to Openship Cloud, move a single project up or bring it home, and (at a high level) open your instance up to a whole team.
- [Scheduled jobs](https://openship.io/docs/guides/jobs.md): Run maintenance on a schedule — the built-in system jobs Openship manages for you, plus your own scheduled commands.
- [Persistent storage & object storage](https://openship.io/docs/guides/persistent-storage.md): Keep the files your app writes — pick the paths that survive a redeploy, or connect an S3 bucket so uploads live outside the container entirely.
- [Deploy from GitHub](https://openship.io/docs/guides/deploy-from-github.md): Connect a GitHub repository and put it online — the step-by-step way and the one-command way.
- [Teams & members](https://openship.io/docs/guides/teams-members.md): Invite other people into your Openship workspace, give them the right role, and understand the difference between your personal space and a shared team.
- [Sleep mode & resources](https://openship.io/docs/guides/sleep-mode-resources.md): Tune what your app costs and how it performs — pick how much CPU, memory, and disk it gets, and choose whether it sleeps when idle or stays on all the time.
- [Billing (Openship Cloud)](https://openship.io/docs/guides/billing.md): Openship Cloud plans and prices are published on the pricing page. Self-hosted Openship is free — there is nothing to bill.
- [Compose & multi-service apps](https://openship.io/docs/guides/compose-multi-service.md): Run an app that's really several pieces at once — web, worker, database — from a docker-compose file or added by hand, and keep every service in sync.
- [Move your setup to another install](https://openship.io/docs/guides/migrate-control-plane.md): Take your whole Openship control plane — servers, projects, services, domains, env vars and secrets — from one install to another. The classic case is a local desktop → an always-on self-hosted server.
- [Git authentication for private repos](https://openship.io/docs/guides/git-authentication.md): How Openship authenticates the git clone when it builds your app — forwarding your local git identity, the server's own git, per-server tokens and SSH keys, and public repos.
- [The edge](https://openship.io/docs/guides/the-edge.md): Openship's built-in reverse proxy — how your apps get a public address and HTTPS, how you protect a route, where your traffic numbers come from, and how to take over a proxy that's already running on a server.
- [Rollback & redeploy](https://openship.io/docs/guides/rollback-redeploy.md): Undo a bad deploy in seconds, re-run one from scratch, and keep an old version safe forever — from the dashboard or the terminal.
- [Server-to-server migration](https://openship.io/docs/guides/server-to-server-migration.md): Move a running project and its data from one of your connected servers to another — no rebuild, volumes streamed host-to-host, with a DNS trick to keep downtime to seconds.
- [Preview environments](https://openship.io/docs/guides/preview-environments.md): Make a separate, safe copy of your project from a git branch — so you can try changes before they reach your real site.
- [Deploy with openship.json](https://openship.io/docs/guides/openship-json.md): Add a declarative openship.json to your repo so Openship builds and deploys it the same way every time — in the wizard and headlessly on push.
- [Custom domains, DNS & SSL](https://openship.io/docs/guides/custom-domains.md): Put your app on your own address like app.example.com, with automatic HTTPS — add the domain, point your DNS, verify, done.
- [Deploy a local folder](https://openship.io/docs/guides/deploy-local-folder.md): Put an app online straight from a folder on your computer — no GitHub required. The desktop picker, the browser upload, and the one-command CLI way.
- [Self-hosted GitHub Apps](https://openship.io/docs/guides/self-hosted-github-app.md): Create and manage workspace-owned GitHub Apps for private repositories, direct webhooks, and short-lived clone tokens without Openship Cloud.
- [Deploy from a template or Git URL](https://openship.io/docs/guides/deploy-template-or-url.md): Two quick ways to start a project without connecting your own GitHub — paste a public repo link, or pick a ready-made starter from the template grid.
- [Environment variables & secrets](https://openship.io/docs/guides/environment-variables.md): Give your app its settings and secrets — add them in the Configuration tab or the CLI, keep the sensitive ones masked, and apply changes without a full rebuild.
- [Logs & monitoring](https://openship.io/docs/guides/logs-monitoring.md): See what your app is doing — its runtime logs, its incoming web requests, and its traffic — and know exactly where to look when something breaks.
- [Backups & restore](https://openship.io/docs/guides/backups-restore.md): Keep safe copies of your app's data, back it up on a schedule, and roll it back when something goes wrong — from the dashboard or the terminal.
- [Third-party email delivery](https://openship.io/docs/guides/email-webmail/relays.md): Route your mail server's outbound mail through an external SMTP relay.
- [OCI Email Delivery](https://openship.io/docs/guides/email-webmail/relay-oci.md): Route your Openship mail server's outbound mail through Oracle Cloud (OCI) Email Delivery — free tier, good IP reputation, no PTR chores.
- [Email & webmail](https://openship.io/docs/guides/email-webmail.md): Run your own self-hosted mail server and a webmail app with Openship — provision it, manage domains and mailboxes, and put an inbox in the browser.

## Optional
- [All docs as one file](https://openship.io/llms-full.txt): every page above concatenated as markdown.