Link your instance to Marfa Cloud

Give your instance a public name under marfa.so without running a tunnel of your own, and unlink it again.

Marfa Cloud gives your instance a public https name, such as https://river.marfa.so, which your phone, other computers and Claude in a chat can all reach. Your instance and its data stay on your computer. The server runs Cloudflare's tunnel connector, cloudflared, which every release installs beside marfa-server, and sends nothing to Marfa Cloud until you start a link. The commands need config.manage.

What alpha means

Marfa Cloud is in alpha, and sign-up is by invitation only.

  • Promised: if Marfa Cloud is down, nothing is lost. The instance can't be reached at its name until it's back.
  • Promised: a name you've reserved stays yours and is never given to anyone else.
  • Not promised: that the service is always available, or that it and the marfa cloud commands won't change.

By default the link moves the sign-in address to the new name, which needs a sign-in from the last fifteen minutes:

Terminal
marfa login --fresh-sign-in
marfa cloud link
Approve the link on this page:
  https://cloud.marfa.so/link
The code on that page must read: WDJB-MJHT

Approve it

Open the page and sign in to Marfa Cloud. Approve only if the page shows the same code; if it differs, the page isn't for your link. On the server's own computer the command opens the page for you.

Confirm the move

The command lists what moving the sign-in address does and asks you to confirm: every browser and app signs out, passkeys are added again at the new name, and the CLI signs in again with marfa login. Without a terminal, pass --confirm-address-change. The address moves only once the name answers as your instance.

--keep-sign-in-address links without moving it. A key can link but can't move the address: the link is made and the command prints the marfa config set sign_in_address command to run from a sign-in. The same happens if the name doesn't answer within fifteen minutes of approval. Ctrl-C leaves the link waiting for approval, and running marfa cloud link again waits on it.

marfa cloud status

It shows the name, the address, the sign-in address and the connector, which is starting, connected or reconnecting while it works. When the connector is failed, the reason says what to do:

ReasonWhat to do
missingPut cloudflared beside marfa-server, or name it with MARFA_CLOUDFLARED. The server tries again on its own.
port_takenAnother program holds the local port the tunnel reaches. Free it, or unlink and link again.
origin_unknownUnlink and link again.
refusedThe server asks Marfa Cloud for a new token itself. If it lasts, unlink and link again.
tokenThe server can't read the tunnel token or write the connector's file.

The connector's output goes to the server's log, and each change of the link raises the event cloud_link.changed.

marfa login --fresh-sign-in
marfa cloud unlink

Unlinking also cancels a link still waiting for approval. If the sign-in address is the Marfa Cloud name, unlinking puts back the one before it, with the same confirmation and sign-out as the move, or unlinks nothing. If Marfa Cloud can't be reached, the instance unlinks anyway and keeps telling it. If you unlink from your Marfa Cloud account instead, the instance notices within the hour and puts the sign-in address back itself.

Run the connector from elsewhere

The server runs cloudflared from beside its own program, never from your PATH. To run another copy, set the start-only setting MARFA_CLOUDFLARED to its absolute path. A server started with MARFA_CONTROL_ONLY can't link, and refuses with no_public_listener.

The rules are in the contract's Cloud chapter, and the operations under Marfa Cloud in the API reference.

On this page