# Remote access Connect a phone, browser, or another desktop app to Moonfold running on a different machine. That machine must stay running and reachable while you work. For Android, use the [mobile app](./mobile-app.md), which pairs with one scan. For the Android app on any network, use **Reach from anywhere** in Settings → Mobile App; see the [mobile app](./mobile-app.md#reaching-your-computer). It works for the app only, because a browser cannot pin the computer's certificate. ## Moonfold Connect (self-hosted only) Moonfold Connect reaches an environment from your other devices through a relay, without router forwarding. Moonfold does not run a relay or an account service, so release builds have Connect turned off. To use it, deploy your own relay from `infra/relay` and your own sign-in service, and build Moonfold with their settings (see `.env.example`). Otherwise use one of the options below: direct pairing on your network, Tailscale, or an SSH tunnel. ### Scripts and agents `moonfold up` asks nothing when you name a choice: `--connect`, `--lan`, or their `--no-` forms. Choices you do not name keep their settings, and `--yes` takes the defaults. Without a terminal: - Moonfold Connect sign-in prints a URL and a code. Approve it on any device. - A needed restart runs without asking, and stops running agent turns. - With nothing set up and no choice named, `moonfold up` stops and names the flags. `moonfold status --json` prints the settings. `moonfold up --help` lists every flag with examples. ### More machines with Moonfold Chat Each Moonfold Connect account can link up to 3 machines. Phones and browsers do not count. A paid Moonfold Chat plan raises the limit to 10 machines with Pro, or 100 with Premier. To link Moonfold Chat, open your account menu on the web or desktop app, go to **Moonfold Chat**, and select **Link Moonfold Chat**. Sign in to Moonfold Chat in the window that opens and approve. The new limit applies the next time you add a machine. If you cancel or downgrade Moonfold Chat, machines you already linked stay linked, but you cannot add more until you are under the limit again. ## Pair over a LAN or private network Use direct pairing when the other device can reach the host's network address. On a desktop host, open **Settings → Sharing & access**, enable **Network access**, then create a pairing link using an address the other device can reach. Changing network access restarts the desktop app. You can turn it off in the same place. For a command-line host, choose the local network in `moonfold up`, or run: ```bash moonfold up --lan ``` For a server in a terminal, run `moonfold serve --lan`. Either way, Moonfold then accepts connections from your local network and tailnet, so a pairing code is all that keeps other devices on them out. If a server is already running, generate a fresh link without restarting it: ```bash moonfold pair ``` Scan the QR code on your phone or paste the pairing URL into **Add environment** in the receiving app. Connection settings are under **Settings → Environments** on web and desktop. A loopback address such as `127.0.0.1` reaches only the device opening the link. On a computer with the desktop app, you can open the printed `moonfold://pair` app link instead. The desktop app asks you to confirm the server address, then adds it. If your HTTPS endpoint uses a certificate from your own certificate authority, install that CA on Android as a **CA certificate** in its security settings; the Android app then trusts it. Pairing authorizes that device for future connections. Use a fresh one-time link for each new device; you do not need the original token to reconnect. Links created in Settings can only be copied from the client that created them while its Sharing & access page stays open. If you leave or reload that page, create another link to share. ### Reach one machine several ways A machine can have more than one route: LAN, Tailscale, another VPN, a public URL, SSH, or Moonfold Connect. Tailscale shares its `100.64.0.0/10` address range with other VPNs such as Cloudflare WARP, so an address in that range shows as VPN unless the machine confirms it is on Tailscale. To add a route, choose **Add route** in the machine's route list, or next to it in the Moonfold Connect list. A pairing link for a saved machine is refused when it comes from an address that machine does not have yet; add that address with **Add route** instead. Pairing again over an address the machine already has still works. A new route is placed by speed, in that order, and you can reorder routes at any time. While connected through Moonfold Connect or a paired address, Moonfold also learns the machine's current LAN and Tailscale addresses and adds them as routes, so pairing once through Moonfold Connect is enough to use the LAN at home. When the machine's LAN address changes, for example after it joins another Wi-Fi network, the learned route follows it. The machine must allow network access for its LAN address to be learned: **Network access** in the desktop app, or the [local network](./background-service.md#local-network-access) choice in `moonfold up`. You can reorder a learned route, but not remove it; it goes away with the route it was learned through, or when the machine stops reporting that address. Moonfold connects over the first route that answers. Away from home, a LAN address that does not answer is checked briefly and skipped. It is only tried again, after the other routes, if none of them connect. While connected over a later route, Moonfold checks the earlier ones when your network changes, when you return to the app, and every minute, and moves back as soon as one works. On web and desktop, select the route count under the machine's name in **Settings → Environments** to see its routes. Drag a route to change the order, or remove it. Signing out of Moonfold Connect removes only that route; a machine you can still reach another way stays saved. Open **Permissions** next to **Routes** in web or desktop to see what your current connection can do on that environment. For a remote environment, this is in its route details. Permissions shown there apply only to the route marked **In use**; other routes are not checked. Direct pairing and Moonfold Connect have separate sessions and may grant different permissions. ### Balance new threads across machines Auto balance is off by default. On web and desktop, enable it in **Settings → Environments → Load balancing** to automatically choose a machine for new threads in projects grouped across connected environments. The section appears once two or more machines are switched on. Each machine starts at **Normal**. Choose **Prefer** to favor it when it has CPU and memory available, **Less often** to reduce its share, or **Manual only** to exclude it from automatic selection. These are preferences, not fixed traffic percentages. Preferences are saved separately in each client. The composer checks eligible machines when choosing a draft's environment, then keeps that choice stable. Choose **Auto balance** again to check current resources, or choose a specific machine to override it. Choosing a branch or worktree also keeps the draft on that machine. Existing threads stay where they started. If resource checks are unavailable or all eligible machines are full, choose a machine manually to continue. ### Tailscale HTTPS Join both devices to the same tailnet. In the desktop app, enable **Tailscale HTTPS** in **Settings → Sharing & access**. Turn it off there to remove that route. To start a command-line server with Tailscale HTTPS: ```bash moonfold serve --tailscale-serve ``` For an already-running server: ```bash moonfold pair --tailscale ``` The pairing link uses an address such as `https://machine.tailnet.ts.net/`. The mapping created by `pair --tailscale` persists across restarts. Remove its default-port mapping with: ```bash tailscale serve --https=443 --set-path=/ off ``` If that port is already in use, choose another with `--tailscale-serve-port`. See `moonfold pair --help` for other pairing options. ### Browser access Moonfold has no hosted web app: a browser connects to the web client your server serves. For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can open it, or pair from the desktop app. An IP address entered without a scheme uses HTTP, so include `https://` when your server uses HTTPS. ## Desktop-managed SSH In the desktop app, open **Settings → Environments → Add environment**, choose **SSH**, and enter a host or SSH alias such as `user@example.com`. Moonfold starts or reuses a server there and opens the port forward for you. Projects, provider credentials, and agent work stay on the remote machine. The remote host must be Linux or an Apple Silicon Mac with `curl` or `wget`, `tar`, `sha256sum` or `shasum`, and [provider setup](./install.md#providers). The first launch downloads Moonfold's server to `~/.moonfold/runtime` on the host, so it takes longer than later ones. Provider CLIs must be on the `PATH` of a non-interactive login shell there; check with: ```bash ssh user@example.com 'sh -lc "command -v claude codex"' ``` If SSH reconnecting fails after an app update, retry the launch once. Removing the connection stops a server that Moonfold launched; a server that was already running is left alone. Each desktop app keeps one session on the host for its SSH connection and reuses it when it reconnects. Revoke sessions you no longer use in **Settings → Sharing & access** on the host, or on a headless host with `moonfold auth session list` and `moonfold auth session revoke `. A desktop that can still sign in over SSH pairs again on its next connect. For Antigravity's Google callback on a remote host, see [remote sign-in](./providers-antigravity.md#sign-in-from-a-remote-device). ## Browser on a remote environment Browser tabs belong to the environment, so you and your agents see the same tabs from any device. The desktop app shows its own environment's tabs directly. Every other device, and the desktop app for other environments, streams them from the host. Agents keep using them while no device is connected, and `localhost` addresses reach servers on the host. The first tab downloads a headless Chrome, about 120 MB, into the Moonfold home. It is the same browser [HTML renders](html-renders.md) use, so a host downloads it only once. Some Linux hosts need [setup](#browser-host-setup) before it can start. Agent tabs have separate storage and share a Chromium process. Take control before typing into an agent's tab, then release control when you want the agent to continue. Read-only connections can watch without changing the page. While you have control, the tab works with your device: text the page copies or cuts goes to your clipboard, a file picker on the page opens your device's picker, and a finished download is offered for you to save. Popups such as sign-in windows open as their own tabs. Downloads stay on the host until the tab closes. Audio does not play on your device. On a phone, tap the floating preview's corner dot to show its controls, then **Pop into separate window** to keep watching in picture-in-picture over other apps. ### Local servers The browser lists ports held by processes your terminals and agents started. Moonfold reads which process holds each port and never connects to it, so a listed port opens as `http://localhost:` and might not be a web page. For an HTTPS server or a specific path, set the **Preview URL** on the project script that starts it; Moonfold checks that address and opens it as written. To stop listing ports, set `MOONFOLD_PORT_DISCOVERY=0` in the environment that starts the Moonfold server, such as [`service.env`](./background-service.md#configure-the-service-environment) for the background service, and restart it. Script preview URLs still appear. ### Browser host setup macOS, Windows, and Linux desktops run the browser as is. Some Linux hosts need one-time setup: Ubuntu 23.10 and later block the sandbox the browser runs in, and minimal images and containers lack libraries it loads. When that happens, the server says so at startup, and browser tabs and HTML previews show the command to run on the host: ```sh sudo moonfold browser setup ``` The server shows the exact line for how you started it, such as `sudo npx moonfold browser setup`, and keeps your `PATH` when Node is installed only for your user. Where `moonfold` is not on your `PATH`, such as with only the desktop app installed, it names the full path of the app's own `moonfold` instead. It allows Chrome's sandbox with an AppArmor profile and installs any missing libraries and system fonts with apt; pages that load without text can mean the host has no fonts. It is safe to run again. Without `sudo`, it only reports what it would change. The browser runs in Chrome's sandbox by default. Chrome cannot start that sandbox as root. If your Moonfold server runs as root, run it as a nonroot user to keep sandboxing enabled. `moonfold browser setup` does not fix this root restriction. If you need to run as root, or cannot enable the sandbox on your host, set `MOONFOLD_SERVER_BROWSER_SANDBOX=0` in the **Moonfold server's environment** and restart the server. This disables Chrome's sandbox. For a manual launch: ```sh MOONFOLD_SERVER_BROWSER_SANDBOX=0 moonfold serve ``` For a systemd service, add `Environment=MOONFOLD_SERVER_BROWSER_SANDBOX=0` under `[Service]` in its configuration, run `sudo systemctl daemon-reload`, then restart your Moonfold service. Setting the variable in an agent's terminal does not change the environment of an already running Moonfold server. ## Connect an outside agent Claude Code, Codex, ChatGPT and other agents Moonfold did not start can drive threads on an environment through its MCP server. See [outside agents](./outside-agents.md) for setup. ## Link another environment Link two machines, such as your laptop and a VPS, and agents on one can work on the other: launch, message, wait on and stop its threads, answer their questions, and manage its queues, projects and scheduled tasks. Linked environments is a beta. Turn it on for both machines in **Settings → Labs**; on mobile, **Settings → Labs** lists each connected machine. While it is off on either machine, agents start nothing over a link between them. A task already running on the other machine still finishes, and if that machine has it off, its result arrives once it is back on. On the machine you will work from, open **Settings → Environments → Linked environments**, choose **Link**, and pick the other machine or enter its address. The list holds the machines this app knows and those on your Moonfold Connect account. If this app is connected to that machine with a session that manages access there, it makes the pairing code itself; otherwise paste one from that machine's **Settings → Sharing & access**. From a terminal, use `moonfold environment link
--pairing-code --access `. You can also ask an agent to link a machine by name, such as "delegate this to my vps". It shows a card in the thread where you pick the machine the same way and the access, then approve. - The access you pick is the most agents from this machine may do there. An agent also never gets more there than its own mode here. - Threads a link starts are marked **From** and this machine's name there. - A full-access link works there like that machine's own agents. Below full access, the link's agents can change only threads it started, not that machine's own threads, projects or settings, and they skip its project setup scripts. - The link shows up in that machine's **Settings → Sharing & access** like any outside agent. Revoke it there to end it. **Forget** on this machine only removes it here. - Links last 30 days. Link again with a new pairing code to renew one. An agent can also hand a task to a linked machine with `delegate_task`: it runs there as an ordinary thread, in the project with the same repository (or the one `target.projectId` names), and this thread wakes with its result when it ends, as for any delegated task. It keeps following the task across restarts. If the other machine revokes the link, or the link is removed here, the task fails with that reason. ## Manage or revoke access On the host, **Settings → Sharing & access** lets authorized administrators create pairing links and revoke client sessions. Revoking an unused link prevents new pairings; revoke a device's session to remove its existing access. Command-line management is available through `moonfold auth --help`. When the app connects to more than one environment, choose one at the top of the page. A desktop app with **Local environment** off can manage a background service on the same machine this way, including its Moonfold Connect link. A session with an open connection stays listed after its access credential expires. To choose a token's permissions, pass `--scope` once for each scope you want: ```sh npx moonfold pair --scope orchestration:read --scope relay:read ``` The selected scopes replace the default permissions. The same option works with `npx moonfold auth pairing create` and `npx moonfold auth session issue`; each command's `--help` lists the available scopes. Without `--scope`, pairing tokens and issued bearer sessions get every permission, including managing access and Moonfold Connect. A terminal or a full-access agent on the host can reach those as well, so a client that should not manage access also needs to go without `terminal:operate` and `orchestration:operate`. To change an existing client's permissions, create a fresh pairing link with the scopes it needs. In a browser opened directly on the environment, open that link to replace the browser's current grant. For a saved remote environment in web or desktop, use **Add Environment** with the fresh link or code; pairing the same environment replaces its saved grant. Reconnecting alone does not change permissions. Grouping checkouts does not combine their permissions. Shared project settings require `orchestration:operate` on every member environment; actions on one checkout use that checkout's permissions. `source-control:write` covers direct Git and pull request changes made from the client: pushing, switching or creating branches, cloning, and removing worktrees. It does not restrict what a task does. Starting a task in a new worktree still creates that branch and worktree with `orchestration:operate`, and the agent it runs can use Git however the environment allows. Settings changes, provider management, environment maintenance, access management, and Moonfold Connect management can each be granted separately. New pairings without `--scope` include all of them. Existing clients keep the permissions they paired with and can stay connected after an update, but newly separated features may require pairing again with the permissions they need. Older clients may show controls that the server denies. Create a fresh pairing link to change a client's permissions. `filesystem:read` allows browsing host files, opening workspace files, and viewing local changes. Add `filesystem:write` to allow editing files or saving plans to the workspace. These scopes control direct file access from the client. To remove an environment from Moonfold Connect, open your account menu's **Moonfold Connect** page. This revokes its cloud access and frees its host space even when the environment is offline or has been wiped. When Moonfold Connect rejects a host's link, the host shows that it was removed from Moonfold Connect. To link it again, turn on **Moonfold Connect** in **Settings → Sharing & access** on a desktop host, or run `moonfold connect link` on a command-line host and then restart Moonfold there. A command-line host that released its tunnel when it last stopped may link itself again on its next start; run `moonfold connect unlink` on that host to keep it off. Removing an environment from a device's connection settings only forgets it on that device and doesn't change your Moonfold Connect account. A device keeps a saved environment after it's deregistered until you remove it from that device. When idle tunnel cleanup is enabled, Moonfold Connect removes a linked environment's tunnel after it stays offline for several minutes. The environment stays linked and keeps the same address. When the host starts again or wakes, Moonfold Connect creates a replacement tunnel on its own. You do not need to pair again. Cleanup usually runs five to ten minutes after the tunnel goes down. Moonfold Connect also removes the tunnel of an environment running an older version of Moonfold once it has been offline for seven days. That environment shows a message asking you to update. Start Moonfold on that computer and update it to the latest version; it reconnects at the same address without pairing again. On a command-line host, `moonfold connect unlink` disables exposure while retaining your login; `moonfold connect logout` also clears that login. Background-service [removal](./background-service.md#manage-the-service) is separate. Treat pairing URLs and authorization codes as passwords. Do not include them in screenshots, logs, or bug reports. ## Moonfold Connect troubleshooting Run `moonfold connect status` on the host to inspect saved authorization and link configuration. It is not a live reachability check. If the environment appears offline, run `moonfold service status` and read the displayed log. If it disappears when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting). | Error | Recovery | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `environment_link_limit_exceeded` or managed tunnel limit | Deregister an unused environment, then restart Moonfold on the host. | | `auth_invalid` or `invalid_bearer` | Run `moonfold connect login`. If credentials were revoked, run `moonfold connect logout`, then `moonfold connect` again. Restart the server after signing in. | | Expired or invalid link proof | Check the host's date and time, update Moonfold, then restart it. | | HTTP 403 without a recognized error | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. | | HTTP 408, 429, or 5xx | Check network and relay availability. Startup retries temporary failures for up to ten minutes. | After fixing a permanent rejection, restart the host's server. On Linux, use `systemctl --user restart moonfold.service` for the background service. For a foreground server, stop it and run `moonfold serve` again with your usual options. Include the diagnostic message and trace ID when reporting a persistent failure. For a connection that still fails after linking, check the date and time on both devices. For server version warnings, follow [Updating Moonfold](./updating.md). ## Using the Desktop App as a Remote Only If a computer should only drive work running elsewhere, turn off its local environment. In the desktop app, open **Settings → Environments** and switch off **Local environment**. Moonfold restarts without a local server: no local agents or terminals run, WSL backends stay off, and other devices can no longer connect to this computer. Your projects, history, and saved connections are kept, and you keep working through pairing, Moonfold Connect, or SSH. Switch **Local environment** back on in the same place to restart with your previous local settings.