Install Mimi Remote and Reach agentd with Localtonet

How Mimi Remote and agentd fit together

Mimi Remote is not a hosted agent service and does not move the primary development environment onto the phone or tablet. The host computer remains the control plane. It runs the agent runtime, retains the project workspace, and provides the host-side gateway used by the mobile app. The iPhone or iPad presents a native interface for following work, continuing a conversation, responding to prompts, handling approvals, and controlling supported session actions.

This distinction matters when planning remote access. Installing the iOS or iPadOS app is only one part of the deployment. A usable connection also requires a functioning agentd service on the macOS, Windows, or Linux computer, a network route from the mobile device to that service, and whatever host pairing or authentication Mimi Remote requires. A tunnel cannot compensate for a missing or unhealthy host service.

Mimi Remote’s project documentation describes direct connections over the same trusted local network or through Tailscale. It also makes clear that the project does not operate its own relay, account system, or hosted session service. If you use Localtonet, our HTTP tunnel becomes the optional public route to an already working agentd HTTP endpoint. The agent sessions still run on your computer.

Mimi Remote is designed around continuing context rather than providing a general-purpose mobile terminal. Its documented interface can display structured replies, execution progress, messages, reasoning, commands, tool calls, and approval requests. Supported controls include adding context, queuing instructions, changing model or reasoning settings, answering prompts, approving an action, and interrupting a turn. More advanced tools can inspect diffs, work with Worktrees, stage changes, commit, push, and open a draft pull request, although those tools are not required for basic use.

Codex is the project’s primary supported runtime. The Claude Code bridge is identified as experimental, so a successful Codex connection does not automatically prove that every Claude Code workflow will behave identically. When diagnosing a problem, separate mobile-to-host connectivity from runtime-specific behavior.

Prerequisites and information to collect

Before installation, prepare the mobile device, host computer, agent runtime, and connection details. The project supports an iPhone or iPad client and includes host-side work for macOS, Windows, and Linux. The supplied project material does not define minimum iOS or iPadOS versions, minimum desktop operating-system versions, or a complete compatibility matrix, so confirm those requirements in the current App Store listing, TestFlight build notes, or repository before committing to a specific device.

Mobile prerequisites

• An iPhone or iPad compatible with the currently distributed Mimi Remote build.
• Access to the App Store release where it is available, access to the project’s TestFlight beta, or a Mac with Xcode 26 if building the iOS app from source.
• Network access to the host through the same LAN for initial testing.
• The host profile and pairing information generated by the Mimi Remote host workflow.

Mimi Remote supports English and Simplified Chinese. It stores tokens for separate host profiles in the Apple Keychain and uses one active connection at a time. Treat every pairing token or host credential as a secret. Do not paste it into screenshots, tunnel names, support messages, shell history, or public issue reports.

Host prerequisites

• A macOS, Windows, or Linux computer that will remain online while mobile access is needed.
• A working Codex environment, or the project’s experimental Claude Code bridge if that is the intended runtime.
• The project’s agentd gateway installed and running.
• The real local bind address, listening port, and applicable endpoint or base URL reported by the installed host component.
• The project’s pairing or authentication material for the mobile client.

The available evidence says that the repository includes agentd for macOS, Windows, and Linux, but it does not provide the complete official installation procedure for that component. It also does not establish a default port, default bind address, service path, startup command, configuration path, environment variable, or credential format. We therefore do not publish speculative commands or defaults in this guide.

Localtonet prerequisites

• A Localtonet account.
• The Localtonet client installed on the computer running agentd, or on another device that can reliably reach its local address and port.
• A device-specific Localtonet authentication token selected without disclosing it.
• A currently available relay server or region selected from our dashboard.
• The verified local IP address and port on which agentd is actually listening.

Install Mimi Remote on iPhone or iPad

There are three documented installation paths: the public App Store release where available, TestFlight for beta builds, and a source build for developers. Choose one path rather than installing multiple variants without a specific testing need. Release and beta builds may not behave identically, and a locally built app can reflect repository changes that have not reached a distributed version.

App Store installation

The public release is the simplest option for most users because iOS or iPadOS handles application installation and updates. Availability can vary, so the wording “where available” is important. If the app does not appear in your App Store, do not install an unrelated application with a similar name. Confirm the official listing through the project’s current repository documentation.

TestFlight installation

TestFlight is intended for beta builds. A beta can contain newer fixes or features, but it can also introduce behavior that differs from the public release. Record the exact app version when reporting a problem, especially when the host package and mobile app were installed at different times.

Building from source

The documented high-level requirement for building the iOS app is a Mac with Xcode 26. The extracted project material does not contain enough information to reproduce the complete source-build procedure safely. In particular, it does not establish the exact Xcode workspace or project file, scheme, signing team setup, package resolution procedure, deployment target, or device registration steps.

For that reason, this guide does not invent a terminal command or pretend that opening an arbitrary project file is sufficient. Use the iOS build guide from the exact repository revision you check out. After the build succeeds, install it on a registered device through Xcode and record the commit or release version so that mobile and host compatibility can be investigated later.

Prepare the host computer and agentd

A remote-development client is only as reliable as its host service. Before working on internet access, make sure the agent runtime works directly on the computer and that agentd stays running. The repository covers macOS, Windows, and Linux, but the supplied evidence does not contain a general-purpose installation command for all three systems.

Start with the agent runtime

Open the host computer and verify that the intended agent can start or resume a session there. Codex is the primary supported runtime. If you are using Claude Code, remember that Mimi Remote labels that bridge experimental. Runtime authentication, model access, quotas, repository permissions, and provider behavior remain separate from the mobile connection.

If the runtime cannot work locally, stop and repair that environment before continuing. Exposing agentd will not fix expired provider credentials, a missing executable, repository permission errors, or an unavailable model.

Install and start agentd using the current project workflow

Use the host package or setup workflow provided by the current Mimi Remote release for your operating system. After installation, use its status interface, logs, or diagnostics to identify all of the following:

• The installed agentd version.
• Whether the service is running continuously rather than repeatedly exiting.
• The actual bind address.
• The actual listening port.
• Whether the endpoint uses plain HTTP locally.
• The mobile pairing or authentication state.

Do not assume that a port seen in an old screenshot, issue, or community post applies to your version. Do not assume that a service bound only to loopback is reachable from another computer on the LAN. Conversely, do not broaden the bind address to every network interface unless the project instructs you to do so and the host firewall is appropriately restricted.

macOS upgrade issue affecting older packages

The v1.0.0 release documents a specific recovery case for users of v0.3.16 or earlier packages. The reported symptoms include the Mac app repeatedly saying that the background service failed during its first start or could not recover after automatic registration. Another symptom is the menu bar app being unable to connect while launchd attempts to restart agentd every three seconds and the process exits immediately with code 1.

The documented cause is version drift. A newer version may have written the configuration for the macOS shared local connection, while an older installed package does not understand that value or its migration. In that case, re-registering the service or reinstalling the same old package does not repair the mismatch.

The release guidance is to install the v1.0.0 Mac DMG over the existing application without deleting the app or configuration directory first. The documented overwrite installation preserves configuration and pairing credentials and does not rotate the token. This advice applies to that identified older-package condition, not to every possible agentd startup failure.

Verify agentd locally before creating a tunnel

Local verification should answer four separate questions: is the service process running, is it listening where expected, does authentication work, and can Mimi Remote maintain its live session connection? A single successful page load does not necessarily prove all four.

If you use a generic HTTP client for a low-level check, substitute only values obtained from your running installation:

curl -i "http://<AGENTD_ADDRESS>:<AGENTD_PORT>/<DOCUMENTED_ENDPOINT>"

The placeholders above are intentional. The available evidence does not establish an endpoint path, and requesting the root path may legitimately return a not-found response even when the service is listening. Use a health or readiness path only if the installed project documentation provides one. Also avoid placing credentials directly in a command because shell history and process inspection can expose them.

Create the Localtonet HTTP tunnel

Once Mimi Remote works over the trusted local route, Localtonet can provide a public address without inbound router port forwarding, a public IP address, firewall reconfiguration, or VPN setup. Our client establishes an outbound connection to a Localtonet relay server. The tunnel remains available only while the selected client device is connected and the tunnel is running.

An HTTP tunnel is the appropriate starting category because agentd is described as a plain HTTP endpoint and the client uses HTTP-based REST and WebSocket communication. The public side of an HTTP tunnel can use an HTTPS address. However, the evidence supplied for this article does not separately document WebSocket compatibility details for every Localtonet client version or configuration. Test live updates, approvals, and reconnection after creating the tunnel rather than relying only on an ordinary HTTP response.

For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation alongside the instructions above. Exact field availability can change by client version, configuration, or plan, so use the current dashboard rather than assuming that every domain option or relay location is available in every subscription.

Validate the public route

Switch the iPhone or iPad away from the original LAN, such as by using a different trusted network, and reconnect through the public HTTPS address. Verify the following behaviors individually:

• The host profile reaches the intended computer rather than an old or duplicate host.
• Pairing or authentication succeeds without putting a token in the public URL.
• Projects and sessions load.
• Live progress continues updating for more than a brief initial request.
• A harmless instruction can be queued and its result appears.
• An approval prompt can be received and handled according to the selected permission mode.
• Temporary network loss results in an understandable disconnect and recovery behavior.

If initial data loads but live updates stop, investigate the persistent connection separately. That pattern often distinguishes basic HTTP reachability from WebSocket, proxy, idle-connection, or reconnection behavior. Capture sanitized Mimi Remote diagnostics and Localtonet tunnel state before changing multiple settings.

Secure remote access to an agent control plane

An agent gateway is more sensitive than a read-only status page. Mimi Remote can expose session content, commands, approval decisions, repository state, and advanced Git actions. A public URL therefore needs deliberate authentication and operational controls even when the public side uses HTTPS.

HTTPS protects the public transport path to the tunnel endpoint, but it is not a substitute for application authorization. Anyone who can reach a public endpoint can attempt to interact with it. Confirm that Mimi Remote’s pairing or authentication remains enforced through the tunnel and that unauthenticated requests do not expose session data or control actions.

Keep provider credentials and Localtonet device tokens separate. Mimi Remote’s project documentation notes that data intentionally sent to Codex, Claude Code, GitHub, voice transcription, or MCP remains handled by those services under their own terms. Localtonet supplies the network route described here; it does not change the data-handling rules of those connected services.

Avoid leaving broad approval modes enabled merely because the mobile interface makes approvals convenient. Before approving an action, inspect the command, affected files, repository state, and current host. The host computer continues to perform the operation with the permissions available to its local account and agent runtime.

Routine operating checklist

• Confirm the expected host and repository before sending instructions.
• Review the active model, reasoning setting, permission mode, and queued turns.
• Keep the host operating system, Mimi Remote components, and agent runtime updated through their official channels.
• After an update, retest local connectivity before blaming the public route.
• Stop the tunnel during long periods when mobile access is unnecessary.
• Rotate affected credentials if a token, pairing code, or private host profile is exposed.
• Preserve sanitized diagnostics before reinstalling or deleting configuration.

Troubleshooting Mimi Remote and Localtonet

The app installs but no host appears

Installation alone does not discover or provision agentd. Confirm that the host package is installed, the gateway is running, and the project’s pairing workflow has been completed. Check that the mobile device is using the intended host profile and that its stored token belongs to that host.

Agentd is not listening

Inspect host status and logs first. A missing process, immediate exit, or restart loop is a host installation problem. Do not create a tunnel to an address and port until an operating-system inspection or project status view proves that something is listening there.

On macOS with a v0.3.16 or earlier package, compare the symptoms with the documented version-drift issue. If they match, use the v1.0.0 release guidance: overwrite the existing app with the release DMG without deleting the app or configuration directory first. If the symptoms do not match, preserve the original error because the same release notes explain that other configuration problems should surface the underlying agentd error rather than be treated as the known version mismatch.

Local access works, but the Localtonet URL fails

Confirm that the Localtonet client is connected, the correct device token was selected, and the tunnel was explicitly started. Then compare the tunnel target with the exact local address and port that succeeded during verification. If Localtonet runs on a different computer, remember that loopback on the Localtonet client refers to that computer, not the computer hosting agentd.

Also check whether a host firewall allows the Localtonet client device to reach the target. We do not require inbound router port forwarding, but the selected client still needs ordinary local connectivity to agentd.

The public endpoint responds, but Mimi Remote will not authenticate

Separate routing from authorization. An HTTP response proves that some service answered, not that the mobile profile contains the right pairing credential. Confirm the selected host profile, token, URL scheme, and any project-required path. Do not disable authentication to test the tunnel. Instead, compare the public profile with the known-working local profile and change only the network address where the project permits it.

Sessions load, but live updates stop

This can indicate that ordinary REST requests work while the persistent connection does not. Reproduce the issue with a safe test session, note how long updates continue, and inspect Mimi Remote’s connection diagnostics. Confirm the tunnel remains running and the Localtonet client has not disconnected. Because the supplied Localtonet context does not establish every WebSocket behavior or timeout for every configuration, retain diagnostics for review rather than inventing a timeout adjustment.

Codex works, but Claude Code does not

Treat this as a runtime-specific issue after confirming that the same mobile-to-host route works for Codex. The Claude Code bridge is experimental, so check bridge readiness, host logs, and compatibility for the exact versions installed. Rebuilding the tunnel is unlikely to fix a bridge configuration problem when ordinary communication already succeeds.

The tunnel worked and then became unavailable

A Localtonet tunnel is available only while its selected client device is connected and the tunnel is running. Check whether the host slept, rebooted, lost connectivity, stopped the Localtonet client, or stopped agentd. Also confirm that the tunnel still targets the same local address and port after host updates or network changes.

A reinstall did not fix the problem

Reinstallation can obscure useful evidence and does not repair every configuration or version mismatch. Record versions and diagnostics first. For the documented older macOS package issue, reinstalling the same old package is specifically not the remedy. Follow the applicable release guidance and avoid deleting pairing data unless the project’s recovery instructions require it.

Frequently asked questions