Ironflow Agent for Zed and JetBrains

@ironflow/agent is a coding agent for editors that speak the Agent Client Protocol (ACP), such as Zed and JetBrains IDEs. You describe a function, a saga or a projection. The agent writes the Ironflow code in your project, runs your typecheck and tests, and fixes what fails.

The agent carries the Ironflow skills (ironflow-start, ironflow-code, ironflow-docs, ironflow-ops, ironflow-fit). It reads exact SDK signatures from them instead of guessing.

You bring your own model key: Anthropic, OpenAI, Google Gemini or OpenRouter. The agent sends your prompts and the files it reads to that provider. Ironflow does not supply or pay for a model.

Platforms: macOS and Linux. On Windows, use WSL.

Before you start

You need Node.js 22.19 or later, because the editor starts the agent with npx.

You also need an Ironflow server for your app. For local work, start one in a second terminal:

ironflow serve --dev

No server yet? brew install sahina/tap/ironflow installs the binary.

Set your model key

Run the login command once. Pick a provider, then paste the key:

npx -y @ironflow/agent login

The key goes to ~/.ironflow/agent/credentials.json with mode 0600. If other users can read the file, the agent refuses to use it. npx -y @ironflow/agent logout removes the key.

You can set an environment variable in the editor’s agent config instead. A variable always wins over the stored key.

If the agent finds no key, it offers login as a terminal login method. An editor that supports terminal authentication runs the command for you. Other editors show a message that names the command.

Add the agent to Zed

Add a custom agent to Zed’s settings.json:

{
  "agent_servers": {
    "Ironflow": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "@ironflow/agent"],
      "env": { "ANTHROPIC_API_KEY": "..." }
    }
  }
}

Leave out env if you used login. Then open the agent panel and select Ironflow.

Add the agent to a JetBrains IDE

Add the agent to ~/.jetbrains/acp.json:

{
  "agent_servers": {
    "Ironflow": {
      "command": "npx",
      "args": ["-y", "@ironflow/agent"],
      "env": { "ANTHROPIC_API_KEY": "..." }
    }
  }
}

For an install from the editor’s agent registry, use the login command. It works the same in both editors.

Ironflow tools and dev mode

The agent can use Ironflow MCP tools to list functions, runs, events, projections, entity streams and KV keys. It starts one ironflow mcp process for each workspace and connects to it on a loopback port. The sessions in that workspace share it, and it stops when the agent stops. This works with ironflow serve --dev.

ironflow must be on your PATH. ironflow mcp uses IRONFLOW_SERVER_URL and IRONFLOW_API_KEY from the agent’s env block. Without them, it finds the server that ironflow serve --dev started in the workspace. In dev mode the server needs no key. If the server is not running yet, the agent says so in its first reply, and the tools work once the server answers.

If the agent cannot start ironflow mcp, it tries the server’s remote MCP endpoint, /api/v1/mcp. ironflow serve --dev does not serve that endpoint, because dev mode accepts any token. If neither works, the agent uses the bundled skills and the ironflow command line only. It tells you in its first reply, with a line that starts with “Ironflow tools unavailable”.

To use the remote endpoint, start a server with remote MCP on, and give the agent a real API key:

IRONFLOW_MCP_REMOTE=true ironflow serve

Then set IRONFLOW_API_KEY (and IRONFLOW_SERVER_URL if the server is not on http://localhost:9123) in the agent’s env block. Remote MCP tells you how to create the key. Run the Ironflow agent against a team server covers the server side.

What the agent can do

The file tools and the search tools stay inside your project folder. A path outside it fails, and no prompt can approve it. The agent’s own folder (~/.ironflow/agent, where the stored key lives) is refused too. Shell commands are not confined, so read each command before you approve it.

Action	What happens
Read files, search files, read skills	Runs with no prompt.
Read from the Ironflow server (functions, runs, events, projections, streams, KV keys)	Runs with no prompt.
Write or edit a file	Asks first. The prompt shows the file path, the old text and the new text.
Run a shell command that only reads inside your project (for example ls, cat, grep, rg, find)	Runs with no prompt, for a fixed set of read-only flags. Any other flag, a path outside the project, .., $( ) or any other program makes it ask. The package README has the exact rules for globs and redirects.
Run any other shell command	Asks first. The prompt shows the full command. A command with no time limit stops after 10 minutes.
Change the Ironflow server (emit an event, invoke a function, append to an entity stream, resume a run, rebuild a projection)	Asks first.
Use a tool from an MCP server that your editor passes in	Asks first.
Delete runs, redact data, read secrets, run SQL	Not offered to the model. A shell command can still reach them if you approve it.
Start sub-agents	Not available.

At each prompt you can allow once, allow for this session, or reject. For the shell, “Allow this exact command this session” covers that command text only. No mode approves edits for you. If you reject a call, the agent does not retry it.

To stop a turn, use the editor’s stop button. Open prompts close, and the turn ends as cancelled.

Sessions and transcripts

The agent keeps a transcript of each session in ~/.ironflow/agent/sessions/, so you can reopen a past session. A transcript holds your prompts, the text of the files the agent read and the output of its tools, in plain text.

When it starts, the agent deletes transcripts older than 30 days. Set IRONFLOW_AGENT_SESSION_DAYS to change this (0 keeps all of them). npx -y @ironflow/agent logout --purge deletes the key and all transcripts.

Settings

Set these in the env block of the agent config, or in your shell.

Variable	Default	Use
ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY	none	Model key. If more than one is set, the first in this order is used.
IRONFLOW_AGENT_MODEL	A default for the provider of the key	Model as provider/model, for example anthropic/claude-sonnet-5-5.
IRONFLOW_AGENT_HOME	~/.ironflow/agent	Where the agent keeps the stored key and the transcripts.
IRONFLOW_AGENT_SESSION_DAYS	30	Transcript retention in days. 0 keeps all of them.
IRONFLOW_SERVER_URL	http://localhost:9123	The Ironflow server for the MCP tools.
IRONFLOW_API_KEY	none	API key for the MCP tools. ironflow mcp and the server’s remote MCP endpoint both use it.

Logs

The agent writes logs to stderr, and your editor shows them in its agent log. The logs carry no prompt text and no keys.