Connect to Cloud & migrate
Link the copy of Alaf Server you run yourself to Alaf Server Cloud, move a single project up or bring it home, and (at a high level) open your instance up to a whole team.
Alaf Server can run in two places. One is your own instance — the copy you installed and manage yourself. The other is Alaf Server 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 Alaf Server 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 Alaf Server 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 Alaf Server 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 Alaf Server Cloud button.
Screenshot
Sign in and give consent
Press Connect to Alaf Server Cloud. A window opens on Alaf Server 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. Alaf Server 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 Alaf Server 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 Alaf Server Cloud (Cloud runs it from now on)
alaf server project transfer <project-id> to-cloud
# Bring a cloud project back to your own instance
alaf server project transfer <project-id> to-self-hostedYou can find a project's id with alaf server 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 Alaf Server onto a VPS you own over SSH, and move your data there. No outside dependency.
- Migrate to Alaf Server 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; Alaf Server 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)
alaf server system migration preflight --server-id <id> --slug myteam
alaf server system migration start --server-id <id> --slug myteam
# To Alaf Server Cloud
alaf server system migration start-cloud
# Keep local, expose via a tunnel
alaf server system migration start-tunnel --slug myteam
# Reverse any of the above, back to single-user
alaf server 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 Alaf Server 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 Alaf Server 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 Alaf Server 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 Alaf Server — 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.