> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Switching

> Move between Moorcheh Cloud and Moorcheh On-Prem without losing either side's agents or sessions.

# Backend Switching

Memanto keeps cloud and on-prem state strictly separated so you can flip between them at will. The data on each side stays intact — switching backends never deletes or moves your agents or memories.

## The Two Backends

| Backend               | Selected with                    | Data lives in         | Auth                                                             |
| --------------------- | -------------------------------- | --------------------- | ---------------------------------------------------------------- |
| **Cloud** *(default)* | `memanto config backend cloud`   | `~/.memanto/`         | `MOORCHEH_API_KEY` in `~/.memanto/.env`                          |
| **On-Prem**           | `memanto config backend on-prem` | `~/.memanto/on-prem/` | None — talks to local Moorcheh server at `http://localhost:8080` |

`memanto status` always shows the **active** backend and its server health.

## Inspect the Current Backend

```bash theme={null}
memanto config backend
```

Sample output (cloud):

```
Active backend: cloud
```

Sample output (on-prem):

```
Active backend: on-prem
Server:    http://localhost:8080
Embedding: ollama
```

## Switch to On-Prem

```bash theme={null}
memanto config backend on-prem
```

What happens:

1. If on-prem has **never been configured** on this machine, the on-prem onboarding wizard runs (Docker check, provider prompts, `moorcheh up`, model pulls). See [On-Prem Quickstart](./quickstart).
2. If on-prem has been configured before, the wizard skips the prompts and **reuses** your previous `embedding_provider`, `embedding_model`, and (where possible) provider API keys from `~/.moorcheh/config.json`.
3. The active session is cleared (sessions are backend-specific — you don't want to send a cloud session token to the on-prem server).
4. `backend: on-prem` is persisted in `~/.memanto/config.yaml`.
5. The in-process client singleton is reset so the next call immediately uses the new backend.

Confirmation:

```
Switched backend to on-prem.
Active session was cleared.
```

## Switch Back to Cloud

```bash theme={null}
memanto config backend cloud
```

If your cloud API key is already saved in `~/.memanto/.env`, the switch is instant. Otherwise the cloud setup prompts you for `MOORCHEH_API_KEY` and verifies it against the Moorcheh API.

## What's Preserved Across Switches

| State                                  | Preserved? | Where                                                                    |
| -------------------------------------- | ---------- | ------------------------------------------------------------------------ |
| **Cloud agents and memories**          | Yes        | Moorcheh Cloud (server-side) + `~/.memanto/agents`.                      |
| **On-prem agents and memories**        | Yes        | Local Moorcheh container + `~/.memanto/on-prem/agents`.                  |
| **Cloud API key**                      | Yes        | `~/.memanto/.env`.                                                       |
| **On-prem provider config**            | Yes        | `~/.memanto/on-prem/state.json` + `~/.moorcheh/config.json`.             |
| **Active session**                     | **No**     | Cleared on every switch (intentional — tokens don't cross backends).     |
| **Integrations (`memanto connect …`)** | Yes        | `~/.memanto/connections.json` — these are IDE wiring, not backend state. |

Switching backends never mutates or deletes data on either side. You can flip back and forth as often as you like.

## Troubleshooting Switches

### "On-Prem Server: ● offline" after switching to on-prem

The wizard sets up the stack but doesn't keep it running across machine reboots. Bring Moorcheh back up:

```bash theme={null}
moorcheh up
```

If `moorcheh` isn't on `PATH`, re-open your terminal (so pip's scripts dir is loaded) or run `python -m moorcheh up`.

### "Invalid Moorcheh API key" after switching to cloud

Your `~/.memanto/.env` is missing or stale. Re-enter the key:

```bash theme={null}
memanto config backend cloud   # triggers the cloud setup flow again
```

Or set it directly:

```bash theme={null}
echo "MOORCHEH_API_KEY=mk_…" > ~/.memanto/.env
```

### Agents missing after switching

Cloud and on-prem maintain **separate** agent registries. An agent created on cloud is not visible from on-prem (and vice versa). Re-create the agent under the target backend, or import a memory export.

## Related

* [On-Prem Quickstart](./quickstart)
* [Configuration](./configuration)
* [Self-Hosting Memanto Server](./server-deployment)