id

Quick Start

Get up and running with ID Agents in minutes

Quick Start#

This guide walks you through installing ID Agents, launching the interactive CLI, deploying your first agents, and sending them messages.

Prerequisites#

Before you begin, make sure you have:

  • Node.js 20 or later
  • PostgreSQL (for agent state persistence)
  • Claude Code or an Anthropic API key
  • id-cli (optional, for onchain agent registration)

Setup#

Clone the repository and install dependencies:

git clone https://github.com/idchain-world/id-agents.git
cd id-agents
npm install

Copy the example environment file and configure it:

cp env.example .env

Edit .env and set at minimum the DATABASE_URL pointing to your PostgreSQL instance:

DATABASE_URL=postgresql://user:password@localhost:5432/id_agents

If you are on a Claude Max plan, run claude login first -- no API key is needed. Otherwise, set ANTHROPIC_API_KEY in your .env file.

Running the Interactive CLI#

Start the manager and CLI with:

npm run id-agents

The manager launches on port 4100 by default. To use a custom port:

npm run id-agents -- --port 5000

Or set it via environment variable:

MANAGER_PORT=5000 npm run id-agents

When the manager starts, agents will be assigned ports starting at 4101 (or your custom port + 1).

Deploying Agents#

Use the /deploy command with a YAML configuration file to spin up agents:

/deploy configs/my-team.yaml

A minimal YAML config looks like this:

version: "1"
team: my-team

defaults:
  runtime: claude-code-cli
  model: claude-opus-4-6

agents:
  - name: coder
    description: "Writes and reviews code"
    workingDirectory: /path/to/project
  - name: researcher
    description: "Research and analysis"
    workingDirectory: /path/to/research

Once deployed, each agent runs as its own local process with a dedicated port and REST-AP endpoints.

Talking to Agents#

Send a message to any deployed agent:

/ask coder Write a hello world function in TypeScript

The agent processes your message asynchronously. You can check for responses:

/news coder

Use /news -l coder to see full message content.

Broadcast to All Agents#

Send a message to every agent at once:

/ask * What is your current status?

Clear a Session#

Start a fresh conversation with an agent:

/clear coder

Registering Agents Onchain#

If you have id-cli installed and ID_REGISTRAR_PRIVATE_KEY set in your .env, you can register an agent on ID Chain:

/register coder

This assigns the agent a permanent ENS-based identity like x.agent-15.sep.xid.eth.

Using the Remote API#

The manager exposes a /remote endpoint for programmatic access. You can execute any CLI command via HTTP:

curl -X POST http://localhost:4100/remote \
  -H "Content-Type: application/json" \
  -d '{"command":"/agents"}'

This is useful for integrating ID Agents into automation workflows and external applications.

Next Steps#