Abstract

Agmente is an iOS client for coding agents that connects to servers supporting the ACP (Agent Client Protocol) or Codex app-server protocol, displaying tool calls, execution results, and conversation history. It supports remote access via Cloudflare Tunnel, enabling deployment of remote ACP agents through standard steps and completion of iOS-side building and testing.

Agmente: The Complete Guide to the iOS Client for Coding Agents | Deployment, Usage & Testing

As a developer, have you ever wanted to conveniently access various coding agents on your iOS device, and view tool call processes, execution results, and complete conversation history in real time? Agmente, an iOS client designed specifically for coding agents, solves this exact need—it seamlessly connects to servers following the ACP (Agent Client Protocol) or Codex app-server protocol, making access to coding agents in mobile scenarios simple and efficient.

1. What is Agmente? What Core Value Does It Offer?

Agmente’s core positioning is as an iOS access entry point for coding agents. It is not a coding agent itself, but acts as a “bridge”: one end connects to servers running the ACP or Codex app-server protocol (whether local or remote), and the other end intuitively displays coding agents’ tool calls, execution results, and full conversation history on iOS devices.

In terms of practical usage value, Agmente’s design is fully centered around developers’ mobile access needs:

• Cross-protocol compatibility: It supports both various coding agents based on the ACP protocol and Codex app-server endpoints, covering mainstream coding agent service forms;
• Mobile access: Break free from desktop limitations—view the full interaction process of coding agents on iPhone/iPad, adapting to mobile office, on-the-go debugging, and other scenarios;
• Secure remote access: Supports a combination of Cloudflare Tunnel + Access credentials, enabling both remote agent access and secure connection protection;
• Lightweight deployment: The accompanying remote agent deployment steps are concise, allowing quick setup of remote coding agent services accessible by Agmente without complex environment configuration.

2. Core Capabilities of Agmente: Key Features You Can Use

To determine if a tool fits your needs, core capabilities are the most critical reference dimension. Agmente’s core capabilities all revolve around “convenient, secure access to coding agents,” and each capability has been validated in real-world scenarios with proven implementability:

1. Support for Multi-Protocol Coding Agent Connections

One of Agmente’s core advantages is compatibility with mainstream coding agent protocols, specifically covering two core protocol systems:

• ACP (Agent Client Protocol) agents: Supports multiple ACP-based coding agents including Copilot CLI, Gemini CLI, Claude Code Adapter, Qwen, and Mistral Vibe. This means the mainstream ACP coding agents you use daily can all be accessed via Agmente on iOS devices;
• Codex app-server endpoints: Specifically adapted to Codex app-server service endpoints, enabling direct connection to corresponding coding agent services without additional protocol conversion.

2. Full Interaction Process Visualization

When using coding agents on iOS devices, the core need is to “see the process clearly and get the results.” Agmente fully displays in the transcript:

• Coding agent tool call behavior: Clearly see which tools the agent calls, the parameters used, and trigger conditions;
• Tool execution results: Return results after each tool call are presented in real time, eliminating the need to switch to a desktop to view them;
• Complete conversation history: All interaction content with the coding agent is retained for subsequent review and debugging.

3. Secure Remote Access Capabilities

If your coding agent is deployed on a remote host (rather than locally), Agmente also provides a mature remote access solution, relying primarily on Cloudflare’s ecosystem security capabilities:

• Cloudflare Tunnel: Exposes the coding agent service on the remote host as an encrypted wss:// endpoint, avoiding security risks from directly opening ports;
• Cloudflare Access credentials: Optional configuration of these credentials further restricts access permissions, ensuring only devices with valid credentials can connect to the remote agent;
• Token authentication: Supports bearer tokens—when remote endpoints are protected by permissions, identity verification can be completed via tokens to ensure access security.

3. How-To: Deploy a Remote ACP Agent and Integrate with Agmente

Many developers deploy coding agents on remote hosts (e.g., cloud servers, private servers). How can Agmente securely access these remote agents? Below are validated, directly implementable steps based entirely on standard command-line operations, with no additional customization requirements.

Preparatory Notes

The core of this hands-on guide is to use the stdio-to-ws tool to convert an ACP agent (taking Copilot CLI as an example) on a remote host into a WebSocket service, then expose it as a wss:// endpoint via TLS encryption for final access by Agmente. All operations are performed in the remote host’s command line, and you must ensure Node.js is installed on the remote host (to meet npx runtime requirements).

Step 1: Launch the WebSocket Service for the Remote ACP Agent

In the remote host’s command line, execute the following command:

npx -y @rebornix/stdio-to-ws --persist --grace-period 604800 "copilot --acp" --port 8765

Command Parameter Explanation (Ensuring Verifiability at Every Step)

• npx -y: Install and run the stdio-to-ws tool directly without manual confirmation;
• @rebornix/stdio-to-ws: The core tool that converts ACP agent services using standard input/output (stdio) into WebSocket services;
• --persist: Enables persistent mode to prevent unexpected service interruptions;
• --grace-period 604800: Sets the graceful shutdown timeout to 604,800 seconds (7 days) to ensure long-term stable service operation;
• "copilot --acp": Specifies the ACP agent command to run (Copilot CLI is used here; this can be replaced with other ACP agent commands such as Gemini CLI or Claude Code Adapter);
• --port 8765: Specifies port 8765 for the WebSocket service to listen on (adjustable based on port usage on the remote host).

After executing this command, a WebSocket service will start on port 8765 of the remote host. This service forwards all requests to the ACP agent started by copilot --acp, making the ACP agent accessible via WebSocket.

Step 2: Stop the WebSocket Service for the Remote ACP Agent (Optional)

If you need to stop the running WebSocket service, execute the following command on the remote host:

pkill -9 -f "stdio-to-ws.*8765"

Command Parameter Explanation

• pkill -9: Force terminates matching processes;
• -f "stdio-to-ws.*8765: Matches all processes containing “stdio-to-ws” and associated with port 8765, accurately terminating the target service to avoid killing other processes by mistake.

Step 3: Expose the Service as an Encrypted wss:// Endpoint

After completing Step 1, the WebSocket service on port 8765 is only accessible within the remote host’s internal network. It needs to be encrypted via TLS and exposed as a public wss:// endpoint (see docs/remote-agent.md for detailed steps). Core requirements:

• Configure a valid TLS certificate for the remote host (obtainable via Cloudflare, Let’s Encrypt, etc.);
• Map the WebSocket service on port 8765 to wss://<your remote host domain/IP> via a reverse proxy (e.g., Nginx) or Cloudflare Tunnel;
• Ensure the exposed endpoint supports HTTPS/WSS encryption; otherwise, Agmente cannot connect securely.

Step 4: Integrate the Remote Agent in Agmente

Open the Agmente app on your iOS device, enter wss://<your-host> (replace with your exposed remote host address) in the connection configuration. If the endpoint is protected by bearer tokens or Cloudflare Access credentials, fill in the credential information in the corresponding fields. Once completed, you can connect to the remote ACP agent and view tool calls, results, and conversation history.

4. Agmente’s Repository Structure and Environment Requirements

To build Agmente’s iOS app yourself (instead of downloading it directly from the App Store), you first need to understand its repository layout and environment requirements—all requirements follow industry standards with no special customized dependencies.

1. Repository Directory Structure

Agmente’s code repository uses a modular design, with different functional modules split into independent directories for easy maintenance and expansion:

Directory Name	Core Function
Agmente/	Core source code for the iOS app, including UI interfaces, interaction logic, protocol adaptation, and other core functions
ACPClient/	Swift package for the iOS app, dedicated to processing ACP protocol parsing, communication, and other logic
AppServerClient/	Client support module for the Codex app-server protocol, responsible for communication and data parsing for this protocol

This directory structure aligns with iOS development best practices. Client logic for different protocols is decoupled, facilitating future expansion of new protocol support and enabling developers to secondary develop specific modules.

2. Build Environment Requirements

Building Agmente’s iOS app requires the following hardware and software requirements—all are standard configurations recommended by Apple:

• Operating System: macOS is required (only macOS supports iOS app building; Windows/Linux cannot complete this);
• Development Tools: Xcode (the latest stable version is recommended to ensure compatibility with the latest iOS SDK and Swift syntax);
• No Additional Dependencies: No third-party tools (e.g., CocoaPods) are required beyond Xcode’s built-in development toolchain—building can be completed directly via Xcode.

5. How-To: Build and Test the Agmente iOS App

If you need to build Agmente yourself (e.g., for customized features or adapting to specific iOS versions), below are two standardized build methods (graphical interface and command line) and corresponding testing methods. All steps are directly verifiable with no vague descriptions.

1. iOS App Building (Two Options)

Option 1: Build via Xcode Graphical Interface (Suitable for Visual Operations)

Steps:

1. Open the Xcode app on macOS;
2. In Xcode, select “Open a project or file”, locate and open the Agmente.xcodeproj file in the Agmente repository;
3. Select the “Agmente” scheme from the Xcode “Scheme” dropdown menu;
4. Select the target device from the “Destination” dropdown menu: either an iOS simulator (e.g., iPhone 16) or a connected iOS physical device;
5. Click the “Run” button (triangle icon) in the top-left corner of Xcode. Xcode will automatically compile the code, build the app, and install it on the selected simulator/physical device.

Option 2: Build via CLI Command Line (Suitable for Automation/Script Deployment)

For building via scripts or automation tools, use the xcodebuild command (Xcode’s built-in command-line build tool). Example command:

xcodebuild -project Agmente.xcodeproj -scheme Agmente -destination 'platform=iOS Simulator,name=iPhone 16'

Command Parameter Explanation

• -project Agmente.xcodeproj: Specifies the Xcode project file to build;
• -scheme Agmente: Specifies the build scheme as Agmente (corresponding to the Scheme in the Xcode graphical interface);
• -destination: Specifies the target device for building—here, the iOS Simulator (iPhone 16). This can be replaced with a physical device’s UDID (format: platform=iOS,name=<device name>,id=<UDID>).

After executing this command, xcodebuild outputs build logs in the terminal. If the build is successful, the corresponding iOS app package (.app file) is generated in the repository’s build directory.

2. Agmente Testing Methods

Testing is critical to ensuring app stability. Agmente provides two standardized testing methods for the iOS app itself and the ACPClient Swift package, respectively.

Test 1: Agmente iOS App Testing

Execute automated app tests using the test parameter of xcodebuild. Example command:

xcodebuild -project Agmente.xcodeproj \
  -scheme Agmente \
  -destination "platform=iOS Simulator,id=<SIMULATOR_UDID>" \
  test

Command Parameter Explanation

• -test: Specifies to execute test tasks instead of build tasks;
• -destination "platform=iOS Simulator,id=<SIMULATOR_UDID>": Specifies the target simulator for testing (replace <SIMULATOR_UDID> with the actual simulator unique identifier);
• Other parameters: Consistent with the build command to ensure the test environment matches the build environment.

After execution, Xcode automatically runs all test cases in the Agmente app and outputs test results (number of passed/failed cases, error messages, etc.) in the terminal.

Test 2: ACPClient Swift Package Testing

ACPClient is Agmente’s core Swift package responsible for ACP protocol processing. Its functionality can be tested independently with the following command:

swift test --package-path ACPClient

Command Parameter Explanation

• swift test: Swift’s official package testing command for executing Swift Package test cases;
• --package-path ACPClient: Specifies the Swift package directory as ACPClient to ensure the testing tool locates the correct package.

After execution, all test cases in the ACPClient package are automatically run to verify the correctness of underlying logic such as ACP protocol parsing, message sending/receiving, and exception handling.

6. FAQ: Common Questions About Agmente

To help you quickly resolve issues you may encounter during use, we’ve compiled the most frequently asked core questions—all answers are based on Agmente’s official design and functional features:

Q1: Which coding agents does Agmente support?

A1: Agmente supports two types of coding agents: (1) Those following the ACP (Agent Client Protocol), including Copilot CLI, Gemini CLI, Claude Code Adapter, Qwen, and Mistral Vibe; (2) Coding agents deployed on Codex app-server endpoints, which can be connected directly without protocol conversion.

Q2: Do I have to deploy a remote agent? Can Agmente connect to local agents?

A2: No. Agmente supports connecting to both ACP/Codex app-server agents on remote hosts and those on the local network (same LAN as the iOS device). Simply enter the local agent’s wss:///ws:// endpoint in the configuration.

Q3: Is Cloudflare Tunnel mandatory?

A3: No. Cloudflare Tunnel is used to ensure secure access to remote agents. If your remote agent is deployed in a trusted internal network and does not require public access, you can directly expose a ws:// endpoint (unencrypted) for Agmente access. However, for public access, we strongly recommend using Cloudflare Tunnel + TLS encryption to avoid data leakage or unauthorized access.

Q4: Is there a fee to build Agmente myself?

A4: No. Agmente is open-source under the MIT License, meaning all source code is freely available, modifiable, and buildable—you only need to meet the macOS + Xcode environment requirements with no additional paid dependencies or licensing fees.

Q5: What scenarios do Agmente’s test cases cover?

A5: Agmente’s iOS app tests primarily cover core scenarios such as UI interaction, protocol communication, and data display. ACPClient Swift package tests focus on underlying logic like ACP protocol parsing, message sending/receiving, and exception handling to ensure stable protocol communication.

Q6: How do I get Agmente?

A6: Two options: (1) Download directly from the App Store (link: https://apps.apple.com/us/app/agmente/id6756249477) without building it yourself; (2) Obtain the source code from the repository and build it yourself on macOS using Xcode.

Q7: How do I ensure access security after deploying a remote agent?

A7: Security can be enhanced in two ways: (1) Configure bearer tokens for remote endpoints, ensuring only devices with valid tokens can access; (2) Enable Cloudflare Access service tokens combined with Cloudflare Tunnel for permission control, providing dual protection for remote access security.

Q8: Is there a strict Xcode version requirement for building Agmente?

A8: We recommend using the latest stable version of Xcode to ensure compatibility with the latest iOS SDK and Swift syntax, avoiding compilation errors due to outdated versions. There is no mandatory minimum version requirement, but Xcode must support the standard iOS app build process.

7. Agmente’s License and Long-Term Usage Notes

Agmente is licensed under the MIT Open Source License (see the LICENSE file in the repository), meaning you can:

• Use all Agmente features for free, for personal or commercial purposes;
• Modify Agmente’s source code to adapt to your personalized needs;
• Distribute Agmente’s build products without paying fees to the original author.

From a long-term usage perspective, Agmente’s design offers excellent scalability:

• The modular repository structure simplifies adding support for new protocols (e.g., future new coding agent protocols);
• Based on standard Swift packages and the Xcode build process, it adapts to Apple’s official iOS development ecosystem without compatibility issues due to version iterations;
• Dependencies such as stdio-to-ws are open-source and actively maintained, ensuring long-term availability of remote agent deployment.

In addition, Agmente’s official documentation system supports long-term usage:

• Complete remote agent deployment guide: docs/remote-agent.md details how to expose remote agents as wss:// endpoints, solving the core problem of public access;
• Local deployment reference: setup.md (local document: Agents.md) provides full-process deployment instructions covering all steps from environment preparation to agent connection;
• No hidden configurations: The implementation logic of all core functions is presented in open-source code, allowing developers to troubleshoot issues and customize development as needed.

8. Summary

As an iOS client focused on coding agents, Agmente’s core value lies in “connecting the link between mobile devices and coding agents”—it is not just a simple “viewing tool,” but a complete solution for extending desktop-side coding agent capabilities to iOS devices.

Whether connecting to local/remote ACP agents or adapting to Codex app-server endpoints; whether ensuring secure remote access via Cloudflare or building customized versions yourself, Agmente provides standardized, verifiable, and easy-to-implement solutions. For developers who need to access coding agents in mobile scenarios, it offers both professional protocol adaptation capabilities and ease of use, making it a reliable choice for coding agent access on the iOS platform.

If you need more detailed deployment guides (e.g., full Cloudflare Tunnel configuration) during use, refer to setup.md (local document: Agents.md) and docs/remote-agent.md in the repository—all documents provide directly actionable steps to ensure every feature can be put into practical use.

From a technical implementation perspective, Agmente’s design follows the principle of “minimal dependencies, standardized processes”: no complex third-party components are required, and building can be completed solely with Apple’s official toolchain; remote agent deployment only requires two core commands, reducing the barrier to use for developers; full-process testing solutions ensure functional stability, allowing developers to use it with confidence in production scenarios.

For technical developers with a college degree or above, Agmente is not only a practical tool but also a typical case for understanding “mobile-side communication with coding agent protocols”—its modular code structure and protocol adaptation implementation logic are worthy of reference as examples for iOS client development.

Key Takeaways

1. Agmente acts as a bridge between iOS devices and coding agents, supporting ACP/Codex app-server protocols and secure remote access via Cloudflare Tunnel.
2. Remote ACP agent deployment relies on stdio-to-ws to convert ACP services to WebSocket, with TLS encryption ensuring secure public access via wss:// endpoints.
3. Agmente can be built via Xcode (graphical/CLI) and tested for core functionality; it is open-source under MIT License with no build/usage fees, and offers strong long-term scalability.