iii.pics Canvas Agent

Use this package when you want Codex or Claude Code on your computer to help operate your iii.pics Canvas.

The Agent is a small local bridge. It runs on your own machine, listens only on 127.0.0.1, and lets the iii.pics /canvas page talk to local AI coding tools through an explicit connection token.

You do not need the iii.pics source code, and you do not need to configure any third-party API key.

Quick start

1. Open iii.pics Canvas in your browser.
2. In a terminal on your computer, run:

npx -y @iii-pics/canvas-agent

3. The terminal prints a local URL and a connect token:

Local URL: http://127.0.0.1:17371
Connect token: xxxxxx

4. In iii.pics Canvas, click Agent → Local, paste the local URL and token, then connect.

After connecting, Codex or Claude Code can read the current canvas, propose node changes, create flows, and trigger canvas generation tools. Write operations are still confirmed in the canvas UI.

What this Agent can do

• Read the current canvas state and selected nodes.
• Create text nodes, prompt nodes, config nodes, and generation flows.
• Connect nodes and update node content.
• Ask the iii.pics Canvas page to run image, text, video, or audio generation through the existing iii.pics account, billing, model, task, and storage system.
• Work with Codex app-server or Claude Code through MCP tools.

Security model

• The HTTP bridge binds to 127.0.0.1 by default.
• The canvas page must provide the correct one-time local token.
• The first successful browser origin is remembered, so another website cannot silently reuse the same local Agent.
• Canvas write operations are routed back to the web page confirmation flow.
• The Agent does not expose your iii.pics login token to Codex or Claude Code.

If you need to reset the remembered browser origin, stop the Agent and remove the local config file shown in troubleshooting below.

Codex MCP setup

If you want Codex CLI or Codex app to use the canvas tools directly, register the MCP server:

codex mcp add infinite-canvas -- npx -y @iii-pics/canvas-agent mcp

The MCP server id remains infinite-canvas for compatibility with existing Codex and Claude Code tool names. The product users see is iii.pics Canvas.

Available MCP tools include:

• canvas_get_state
• canvas_get_selection
• canvas_export_snapshot
• canvas_apply_ops
• canvas_create_text_node
• canvas_generate_text
• canvas_generate_image
• canvas_generate_video
• canvas_generate_audio
• canvas_create_generation_flow
• canvas_create_config_node
• canvas_run_generation
• canvas_update_node
• canvas_connect_nodes

Claude Code MCP setup

Claude Code can use the same MCP server:

claude mcp add --scope user --transport stdio infinite-canvas -- npx -y @iii-pics/canvas-agent mcp

When Claude Code is used through the local Agent, canvas write operations still go through the browser-side confirmation policy.

Troubleshooting

The canvas cannot connect

Check that the terminal still shows the Agent running, then confirm:

• URL starts with http://127.0.0.1: or http://localhost:.
• Token matches the latest Connect token printed by the Agent.
• Browser extensions or security software are not blocking loopback requests.

You can also open:

http://127.0.0.1:17371/config

This endpoint confirms the Agent is reachable. It does not reveal the token.

Port 17371 is already in use

Start the Agent on another local port:

PORT=17372 npx -y @iii-pics/canvas-agent

On Windows PowerShell:

$env:PORT = "17372"; npx -y @iii-pics/canvas-agent

Reset remembered origins or tokens

The Agent stores local connection data under your home directory:

~/.infinite-canvas/canvas-agent.json

This legacy directory name is kept for compatibility with existing installs. You can delete the file to force a fresh local URL/token and browser-origin handshake.

For developers

The published package is @iii-pics/canvas-agent. Normal users should run it with npx; they do not need a source checkout.

Repository integration notes, upstream provenance, and development logs live in the iii.pics project repository, not in this npm user guide.