Connect to Cloud & migrate
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.
Openship can run in two places. One is your own instance — the copy you installed and manage yourself. The other is Openship Cloud — the managed version, where we run the servers, SSL, and the global network for you. Think of it like a workshop: you can build things in your own garage, or rent a fully-equipped bench at a shared makerspace. This guide is about connecting the two, and moving work between them.
There are three separate things people mix up, so let's name them up front:
- Connecting — link your instance to a Cloud account so cloud features light up. Nothing moves.
- Promoting a project — take one existing project and hand it to Cloud to run. It moves.
- Team-mode migration — turn your whole single-user instance into a shared, multi-user setup.
What you need first
- Your own Openship instance, up and running (you can see the dashboard). The Cloud settings tab only appears on self-hosted instances — on Cloud itself there's nothing to connect.
- To be the workspace owner. Connecting and disconnecting Cloud is an owner-only action.
- An Openship Cloud account. You sign in — or create one — in the window that opens during the connect step, so you don't need one beforehand.
Connect your instance to Openship Cloud
This links your instance to a Cloud account. It does not move any of your projects — it just unlocks the option to deploy to Cloud and to use Cloud-backed features.
Open the Cloud settings
In the dashboard, go to Settings and choose the Cloud tab from the left. You'll see a card that says Connect to Cloud with a Connect to Openship Cloud button.
Screenshot
Sign in and give consent
Press Connect to Openship Cloud. A window opens on Openship Cloud and asks you to sign in, then to authorize the connection — this is the "do you allow this?" consent step, the same idea as connecting an app to your Google or GitHub account. Say yes.
When the window closes, the card flips to a green Connected badge showing the Cloud account you linked.
Screenshot
Connecting doesn't move anything
After connecting, your projects still run exactly where they were. The connection just gives your instance permission to talk to Cloud. To actually move a project, see the next section.
Disconnecting
On the same card, the Disconnect button unlinks the account. Openship asks you to confirm first, because cloud deployments stop working until you reconnect, and disconnecting also drops the shared GitHub connection that rides on the cloud link — so any repos connected through Cloud will need reconnecting afterward.
Move one project to Cloud (and back)
Once connected, you can hand a single self-hosted project to Cloud to run — this is called promoting. You can also pull a cloud project back down to your own instance — bringing it home.
Who owns a cloud project?
This is the important boundary. Once a project lives on Openship Cloud, Cloud owns it — the cloud copy is the one true copy. Your instance keeps a pointer to it and acts as a gateway in front of it, so it still shows up in your dashboard, but the real project lives on Cloud. Bringing it home reverses that and makes your instance the owner again. For the full picture, see Cloud as source.
Today this move is done from the CLI. Both directions are self-hosted-only, and your instance must be connected to Cloud first (from the section above).
# Promote a project up to Openship Cloud (Cloud runs it from now on)
openship project transfer <project-id> to-cloud
# Bring a cloud project back to your own instance
openship project transfer <project-id> to-self-hostedYou can find a project's id with openship project list. Under the hood these call
POST /api/projects/:id/transfer/to-cloud and .../to-self-hosted.
Open your instance to a team (migration)
Everything above keeps your instance single-user — only you sign in. When you're ready for teammates, you migrate the whole instance into multi-user mode. This is a bigger, one-time move, so here's just the shape of it — the full walkthrough lives in Teams & members.
Go to Settings → Team. While the instance is still single-user, the owner sees a Team workspace card with a Migrate button. Pressing it opens the Move to multi-user mode chooser with three paths:
- Migrate to your server — deploy Openship onto a VPS you own over SSH, and move your data there. No outside dependency.
- Migrate to Openship Cloud — push your data up to Cloud and let us host everything. Your local instance becomes a launcher that points at Cloud. (Requires the Cloud connection above.)
- Keep local, expose via tunnel — your data stays on this machine; Openship opens a public tunnel so teammates can reach you while your machine is online. (Also requires the Cloud connection.)
Screenshot
You can switch back
Migration isn't a trap door. Whichever path you pick, your local data stays on disk, and you can return to single-user mode later. Moving to Cloud also won't send your secrets — encrypted fields are stripped before the upload.
The same migration from the terminal
If you'd rather script it, the system migration commands map to the same three paths, plus a reversal:
# To your own server (run a read-only readiness check first)
openship system migration preflight --server-id <id> --slug myteam
openship system migration start --server-id <id> --slug myteam
# To Openship Cloud
openship system migration start-cloud
# Keep local, expose via a tunnel
openship system migration start-tunnel --slug myteam
# Reverse any of the above, back to single-user
openship system migration switch-backIf something goes wrong
There's no Cloud tab in Settings
The Cloud tab only shows on a self-hosted instance. If you're already using Openship Cloud, there's nothing to connect — cloud features are on by default. If you are self-hosting and still don't see it, make sure you're signed in as the workspace owner.
“This organization is not connected to Openship Cloud”
A transfer or a Cloud migration ran before the instance was linked. Connect first in Settings → Cloud
(you must be the owner), then run the command again.
The connect window closes but the card still says “Connect”
The sign-in or consent step didn't finish. Press Connect to Openship Cloud again and complete both the sign-in and the Authorize step in the popup. If your browser blocks pop-ups, allow them for the dashboard and retry.
What next?
Cloud as source
Why a cloud project is owned by Cloud, and how your instance proxies to it.
Cloud boundary
Exactly what crosses the line to Cloud — and what never leaves your machine.
Teams & members
The full multi-user migration walkthrough, roles, and invites.
Data ownership
Export and import everything, so there's no lock-in either way.
Email & webmail
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.
Sleep mode & resources
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.