acp-port

Connect a model API to your editor through the Agent Client Protocol.

acp-port is a TypeScript CLI that runs as an ACP coding agent. It connects an ACP-capable editor to local model servers, LLM gateways, and cloud APIs. The editor provides the conversation UI, workspace context, permissions, and optional file/terminal access; acp-port handles model discovery, streaming responses, conversation history, and the model's tool loop. File tools use the local workspace when the editor does not provide file access.

Use it with LM Studio, Ollama, LiteLLM, OpenRouter, OpenAI, Anthropic, or Google's OpenAI-compatible Gemini endpoint. Choose the endpoint and model you want to use, then register acp-port as a custom agent in your editor.

Documentation

| I want to… | Start here | | --- | --- | | Run it for the first time | Quick start | | Connect Zed, JetBrains Air, JetBrains AI Assistant, or another ACP client | Editor integration | | Configure a particular model server or cloud service | Provider guide | | Understand every CLI flag, environment variable, and default | Configuration reference | | Understand tools, permissions, data flow, and limits | Capabilities and limits | | Diagnose startup, model, authentication, or tool errors | Troubleshooting | | Develop, test, or contribute to the project | Contributing | | Configure automatic versions, changelogs, tags, and npm publishing | Release guide | | Understand the implementation or add a provider/tool | Architecture and extension guide |

How it works

ACP standardizes communication between editors and coding agents. acp-port implements the agent side and translates model API responses into ACP messages.

flowchart LR
    Editor["ACP editor / IDE"] <-->|"ACP over stdin/stdout"| Agent["acp-port"]
    Agent <-->|"HTTP: model discovery + streaming inference"| API["Local server or cloud API"]
    Agent -->|"File, terminal, and permission requests"| Editor

A typical turn works like this:

1. The editor launches acp-port and opens a session with a workspace directory.
2. acp-port discovers the endpoint's models and returns a model selector to the editor.
3. Your prompt and conversation history go to the selected model API.
4. Text streams back to the editor. If the model requests a tool, acp-port validates the request and uses the editor's ACP file or terminal capability. File operations use the local workspace when the corresponding editor capability is absent.
5. Tool results go back to the model, which can continue working or finish the turn.

The CLI starts a process that speaks ACP over stdio. It has no interactive terminal chat UI or HTTP listening port. Model servers still run separately. Model discovery lists available IDs; it does not download weights. acp-port does not launch other coding agents or run MCP servers.

Quick start

1. Run with npx

Requires Node.js 22.12 or later, with npm and npx available. Run the published CLI directly:

npx -y acp-port --version
npx -y acp-port --help

No repository checkout, build step, or global installation is needed for the npm release. npx downloads the package when needed, and -y skips npm's installation confirmation so editor launches can proceed without an interactive prompt. See the npm npx reference.

Release status: acp-port is not yet available on the public npm registry. The npx examples describe usage after the first npm release. To try the unpublished source or contribute changes, follow CONTRIBUTING.md.

2. Start your endpoint and check its models

For LM Studio, download a suitable chat model in LM Studio and start its local API server. For the usual local port:

API_KEY='' npx -y acp-port models --base-url http://127.0.0.1:1234/v1

For a running Ollama server with a model already downloaded:

API_KEY='' npx -y acp-port models --base-url http://127.0.0.1:11434/v1

For an authenticated gateway, set API_KEY in the process environment:

API_KEY=YOUR_GATEWAY_KEY npx -y acp-port models \
  --base-url https://gateway.example.com/v1 --json

The local examples clear any inherited key for an unauthenticated server; substitute its token if you enabled authentication. The inline environment syntax above is for POSIX shells. In PowerShell, use $env:API_KEY = "YOUR_GATEWAY_KEY" (or "" for no key) before running the command. Editor examples use an env object instead.

models prints a catalog and exits. A catalog entry such as endpoint/vendor/model contains an internal endpoint prefix; pass only the upstream ID, vendor/model, to --default-model.

If your server cannot list models, provide a known model ID:

npx -y acp-port models \
  --base-url http://127.0.0.1:1234/v1 \
  --default-model YOUR_MODEL_ID --no-discovery

With discovery disabled, this command checks the configured catalog without contacting the endpoint. Your first editor prompt tests inference. See the provider guide for server preparation, authentication, and compatibility requirements.

3. Add it to your editor

For Zed, add a custom agent under agent_servers in your settings:

{
  "agent_servers": {
    "LM Studio via acp-port": {
      "type": "custom",
      "command": "npx",
      "args": [
        "-y", "acp-port",
        "--base-url", "http://127.0.0.1:1234/v1",
        "--default-model", "YOUR_MODEL_ID"
      ],
      "env": { "API_KEY": "" }
    }
  }
}

Replace YOUR_MODEL_ID with an upstream ID from discovery. Setting API_KEY to an empty string deliberately disables authentication for this local endpoint, even if the editor inherits a key from your shell. Set the endpoint's actual key when authentication is enabled. If the editor cannot find npx, see the launch settings and PATH guidance.

Open a project, select this agent, and start a conversation. An explicit --default-model chooses the initial model; other discovered models remain selectable. Without it, acp-port selects the first discovered model, which may not be the model you want for coding.

The editor integration guide includes copyable configurations for Zed and JetBrains, multiple endpoints, Windows paths, remote workspaces, and a first-session smoke test.

Choosing a provider

--provider selects an API adapter. --base-url selects the actual server. For example, --provider openai --base-url http://127.0.0.1:11434/v1 sends requests to Ollama using the OpenAI API format.

| Service | Adapter | Base URL | Authentication | | --- | --- | --- | --- | | LM Studio | openai (default) | http://127.0.0.1:1234/v1 | Optional, depending on server settings | | Ollama | openai | http://127.0.0.1:11434/v1 | Usually omitted for a local server | | LiteLLM | openai | Your gateway's API base URL | Gateway key, when required | | OpenRouter | openai | https://openrouter.ai/api/v1 | OpenRouter API key | | OpenAI | openai | https://api.openai.com/v1 (default) | OpenAI API key | | Anthropic | anthropic | https://api.anthropic.com (default for this adapter) | Anthropic API key | | Gemini | gemini | https://generativelanguage.googleapis.com/v1beta/openai (default for this adapter) | Gemini API key |

All CLI providers read API_KEY. Variables such as OPENAI_API_KEY do not configure this CLI. Anthropic and Gemini require a nonblank key; the OpenAI adapter allows unauthenticated local servers, but the hosted OpenAI service requires authentication. See provider setup and official API references.

OpenAI, Gemini, and compatible gateways use streaming Chat Completions. Anthropic uses the native Messages API. The endpoint must support the selected protocol; a model appearing in /models does not establish chat support, tool support, or account access to inference. The OpenAI Responses API is not implemented.

Each CLI process connects to one endpoint. Create separate editor entries to use multiple servers or credentials. Requests do not automatically fall back to another provider.

Commands and settings

# Inspect the available options.
npx -y acp-port --help

# Discover models without starting an ACP session.
npx -y acp-port models --base-url http://127.0.0.1:1234/v1 --json

# Start the ACP agent; omitting "serve" has the same effect.
npx -y acp-port serve --base-url http://127.0.0.1:1234/v1

# Use a known model without a model-list request.
npx -y acp-port --base-url http://127.0.0.1:1234/v1 \
  --default-model YOUR_MODEL_ID --no-discovery

| Option | Purpose | | --- | --- | | --provider openai\|anthropic\|gemini | Choose the API format and default URL. Defaults to openai. | | --base-url URL | Override the API base URL. | | --default-model MODEL_ID | Select one initial upstream model ID and keep it available if discovery fails. | | --name NAME | Set the endpoint label used in model names. | | --no-discovery | Skip model discovery. Requires --default-model. | | --no-tools | Omit all tools for models that only support text chat. | | --mode MODE | Choose manual (default), accept-edits, plan, auto, or full-access. Supporting editors also offer a per-session mode selector. | | --json | Print structured catalog data with the models command. | | --help, -h, --version | Print usage or version and exit. |

Connection options and API_KEY are supplied per launch. There is no acp-port configuration file, automatic .env loading, or interactive sign-in flow. Your editor's settings file configures how the editor launches the process.

The configuration reference documents validation, model IDs, environment handling, and fixed CLI limits. Settings without CLI flags, such as custom headers, timeouts, and the system prompt, require source changes.

Capabilities and limits

• Streams text and accepts embedded text resources. Resource links supply metadata; their contents are not automatically fetched.
• Exposes read_file, write_file, list_directory, search_files, and run_command when tools are enabled. File and command tools work locally when the editor does not provide them. Plan mode exposes only reading, listing, and searching.
• By default, requests editor permission before each write or command and restricts file paths and command working directories to the session workspace. Reads, listings, and searches do not request approval.
• --mode full-access works with any ACP IDE or editor: all five tools run locally without approval prompts or workspace path restrictions. Commands inherit the agent's environment and OS permissions; this does not grant administrator privileges or provide an OS sandbox. Local reads use saved disk contents.
• --mode accept-edits automatically allows workspace writes but asks before commands. --mode auto can remember explicit session approvals for a file or exact command. --mode plan prevents writes and command execution. Modes can also be selected through ACP; changing a mode cancels the current turn and clears remembered approvals.
• Keeps sessions in memory. Restarting the agent loses their history; session reload and automatic history summarization are unavailable.
• Defaults to 12 model requests per turn, 200,000 history characters, and 120-second provider/tool timeouts. A character budget is not a model token budget.
• Supports text-based coding workflows. Images, audio, binary attachments, and MCP tools are unsupported. Forwarded MCP servers are ignored with a warning on stderr; chat and supported editor tools remain available.

Prompts, attached text, conversation history, and tool results are sent to the selected model endpoint. Choose that endpoint with your workspace's data requirements in mind. See capabilities and limits for the exact tool behavior and data flow.

Automated tests cover mocked provider APIs, ACP sessions, permission handling, and a stdio tool round trip. They do not establish compatibility with every model or replace a live test in your editor. For common failures, see troubleshooting.

Development

pnpm install --frozen-lockfile
pnpm run dev --help
pnpm run dev models --base-url http://127.0.0.1:1234/v1
pnpm run check
pnpm run build
pnpm run format:check
pnpm run lint:check

Use Node.js 24.21.0 and pnpm 12.8.1 for development; mise install installs these versions from mise.toml. Source development requires Node.js 22.14.0 or newer because of the release tooling, while the published CLI supports Node.js 22.12.0 or newer. The committed pnpm-lock.yaml makes local and CI installs repeatable.

The project uses TypeScript, native ESM, the ACP SDK, Zod, and the OpenAI/Anthropic SDKs. Tests run directly from TypeScript with Node's test runner and tsx; a build is not required to run them. Editors using dist/cli/index.js require a new build and process restart to pick up source changes.

Read CONTRIBUTING.md for the local workflow, focused tests, package checks, and contribution guidance. GitHub Actions checks Node.js 22 and 24, then semantic-release publishes qualifying commits from the default branch with a changelog, Git tag, and GitHub Release. See the release guide for the one-time npm and GitHub setup. The architecture guide maps the internal modules, explains the session/tool loop, and walks through adding providers and tools.

Migrating from older configuration

File-based configuration and external-agent management are no longer supported. acp-port.json and ACP_PORT_CONFIG are ignored, and old configuration files are left on disk. Move connection settings into each editor entry's arguments and env.API_KEY. Replace old options with those in the configuration reference.

The ACP agent registry distributes ready-made agents. It is separate from a model server's catalog. acp-port connects model APIs to ACP; it does not install or launch agents from that registry.

License

MIT.