# Link your instance to Marfa Cloud (/run/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 [#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.

## Link it [#link-it]

### Start the link [#start-the-link]

By default the link moves the [sign-in address](/run/address#move-the-address) to the new name, which needs a sign-in from the last fifteen minutes:

```bash
marfa login --fresh-sign-in
marfa cloud link
```

Output:

```text
Approve the link on this page:
  https://cloud.marfa.so/link
The code on that page must read: WDJB-MJHT
```

### Approve it [#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 [#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.

## Check the link [#check-the-link]

```bash
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:

| Reason | What to do |
| - | - |
| `missing` | Put `cloudflared` beside `marfa-server`, or name it with `MARFA_CLOUDFLARED`. The server tries again on its own. |
| `port_taken` | Another program holds the local port the tunnel reaches. Free it, or unlink and link again. |
| `origin_unknown` | Unlink and link again. |
| `refused` | The server asks Marfa Cloud for a new token itself. If it lasts, unlink and link again. |
| `token` | The 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](/catalog/events) `cloud_link.changed`.

## Unlink it [#unlink-it]

```bash
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 [#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](/reference/instance-settings#start-only-settings) `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](https://github.com/withmarfa/marfa/blob/main/conformance/spec/cloud.md), and the operations under [Marfa Cloud](/reference/api/marfa-cloud/startCloudLink) in the API reference.
