AI Agent Tutorial: Install and Run Ironclaw with OpenAI

March 11, 2026

Modern infrastructure is increasingly automated using AI agents.

Instead of manually running commands or writing scripts, an AI agent can reason about tasks, interact with APIs, execute commands, and complete workflows autonomously.

In this tutorial we will install and run an AI agent using Ironclaw, a framework designed for building autonomous agents powered by OpenAI models.

By the end of this guide you will learn how to:

• Install Ironclaw on Ubuntu
• Configure OpenAI API access
• Run an AI agent locally
• Execute automated tasks
• Understand real-world AI agent use cases

What is an AI Agent?

An AI agent is a system that can:

Understand a goal
Plan actions
Execute tasks
Observe results
Improve its next step

Unlike a simple chatbot, an agent can interact with systems and tools.

Example tasks:

• writing code
• managing cloud infrastructure
• interacting with APIs
• automating workflows

AI agents typically combine:

Large Language Models (LLMs)
Tool integrations
Memory
Execution environments

What is Ironclaw?

Ironclaw is an AI agent framework designed to run autonomous tasks using LLMs. IronClaw is powered by NEAR AI’s cryptographically secure infrastructure, which ensures your credentials never leave the vault. IronClaw is built on a simple principle: your AI assistant should work for you, not against you. IronClaw is the AI assistant you can actually trust with your personal and professional life.

Key capabilities:

• Your data stays yours - All information is stored locally, encrypted, and never leaves your control • Transparency by design - Open source, auditable, no hidden telemetry or data harvesting. • Self-expanding capabilities - Build new tools on the fly without waiting for vendor updates • Defense in depth - Multiple security layers protect against prompt injection and data exfiltration • interaction with APIs and external services

Ironclaw can be connected to LLM providers such as OpenAI.

This allows the agent to reason and execute tasks based on prompts.

Architecture of an AI Agent

Example architecture:

User Request
     |
     v
AI Agent (Ironclaw)
     |
     +---- LLM reasoning (OpenAI)
     |
     +---- Tools
           |
           +-- Shell commands
           +-- APIs
           +-- GitHub
           +-- Cloud infrastructure

The LLM performs reasoning while the agent executes real-world actions.

Prerequisites

Before installing Ironclaw ensure you have:

• Ubuntu 22.04 or newer with Confidential VM service GCP Confidential VM • Python installed
• Git installed
• OpenAI API key
• Rust 1.85+ • PostgreSQL 15+ with pgvector extension

Optional but recommended:

• Docker
• isolated VM environment

Install Dependencies

Update the system.

sudo apt update
sudo apt install git python3 python3-pip curl wget build-essential pkg-config libssl-dev clang -y

Install NodeJs

    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
    apt install nodejs -y
    node -v
    npm -v

Install Codex

    npm install -g @openai/codex

Install cargo and rustc

curl https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env
cargo --version
rustc --version

Istall Postgresql with pgvector

apt install -y postgresql postgresql-contrib postgresql-16-pgvector
systemctl enable postgresql
systemctl start postgresql
psql --version

Install go

wget https://go.dev/dl/go1.22.4.linux-amd64.tar.gz
tar -C /usr/local -xzf go1.22.4.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

Setup Postgresql

sudo -u postgres psql
psql (16.13 (Ubuntu 16.13-1.pgdg24.04+1))
Type "help" for help.

postgres=#createdb ironclaw
postgres=# CREATE USER ironclaw WITH PASSWORD 'Your Password';
postgres=# ALTER DATABASE ironclaw OWNER TO ironclaw;
postgres=# GRANT ALL PRIVILEGES ON DATABASE ironclaw TO ironclaw;
postgres=# GRANT ALL ON SCHEMA public TO ironclaw;
postgres=#\q
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

Clone Ironclaw Repository

Clone the project.

git clone https://github.com/nearai/ironclaw.git

Enter directory.

cd ironclaw

Build ironclaw

cargo build --release

This installs ironcalw binary.

Configure OpenAI API Key

Create environment variable.

export OPENAI_API_KEY="your-api-key"

You can also permanently store it in:

~/.bashrc

Example:

echo 'export OPENAI_API_KEY="your-api-key"' >> ~/.bashrc
source ~/.bashrc

Start Ironclaw Agent onboard

Run the agent.

./target/release/ironclaw onboard

The agent will start interacting with the configured LLM.

Example prompt:

╭─────────────────────────╮
│  IronClaw Setup Wizard  │
╰─────────────────────────╯
Step 1/9: Database Connection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Existing database URL: postgresql://ironclaw:****@localhost:5432/ironclaw
Use this database? [Y/n] Y
✓ Database connection successful
Step 2/9: Security
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Secrets master key found in SECRETS_MASTER_KEY environment variable.
✓ Security configured (env var)
Step 3/9: Inference Provider
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Select your inference provider:

Provider:

  [1] NEAR AI          - multi-model access via NEAR account
  [2] Anthropic        - Claude models (direct API key)
  [3] OpenAI           - GPT models (direct API key)
  [4] Ollama           - local models, no API key needed
  [5] OpenRouter       - 200+ models via single API key
  [6] OpenAI-compatible - custom endpoint (vLLM, LiteLLM, etc.)

> 2
ℹ ANTHROPIC_API_KEY found: sk-ant...EQAA
Use this key? [Y/n] Y
✓ Anthropic configured (from env)
Step 4/9: Model Selection
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Available models:

Select a model:

  [1] claude-3-haiku-20240307
  [2] claude-haiku-4-5-20251001
  [3] claude-opus-4-1-20250805
  [4] claude-opus-4-20250514
  [5] claude-opus-4-5-20251101
  [6] claude-opus-4-6
  [7] claude-sonnet-4-20250514
  [8] claude-sonnet-4-5-20250929
  [9] claude-sonnet-4-6
  [10] Custom model ID

> 6
✓ Selected claude-opus-4-6
Step 5/9: Embeddings (Semantic Search)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Embeddings enable semantic search in your workspace memory.

Enable semantic search? [Y/n] Y
Select embeddings provider:

  [1] OpenAI (requires API key)

> 1
✓ Embeddings configured for OpenAI
Step 6/9: Channel Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


ℹ Tunnel Configuration (for webhook endpoints):
ℹ A tunnel exposes your local agent to the internet, enabling:
ℹ   - Instant Telegram message delivery (instead of polling)
ℹ   - Slack, Discord, GitHub webhooks

Configure a tunnel? [y/N] N

Which channels do you want to enable?

  (Use arrow keys to navigate, space to toggle, enter to confirm)

  > [x] CLI/TUI (always enabled)
    [ ] HTTP webhook
    [ ] Signal
    [ ] Discord (will install)
    [ ] Slack (will install)
    [ ] Telegram (will install)
    [ ] Whatsapp (will install)

The agent will generate and execute steps to complete the task.

Finally run to get WebUI

./target/release/ironclaw run
2026-03-12T04:08:49.910846Z  INFO Starting IronClaw...
2026-03-12T04:08:49.916599Z  INFO Loaded configuration for agent: ironclaw
2026-03-12T04:08:49.917113Z  INFO LLM backend: anthropic
2026-03-12T04:08:49.961658Z  INFO PostgreSQL database connected and migrations applied
2026-03-12T04:08:49.976459Z  INFO Configuration reloaded from database
2026-03-12T04:08:50.045839Z  INFO Using Anthropic direct API (model: claude-sonnet-4-20250514, base_ur       l: default)
2026-03-12T04:08:50.047093Z  INFO LLM provider initialized: claude-sonnet-4-20250514
2026-03-12T04:08:50.047121Z  INFO LLM retry wrapper enabled max_retries=3
2026-03-12T04:08:50.056785Z  INFO Safety layer initialized
2026-03-12T04:08:50.102452Z  INFO Registered 4 built-in tools
2026-03-12T04:08:50.102829Z  INFO Embeddings enabled via OpenAI (model: text-embedding-3-small, dim: 1       536)
2026-03-12T04:08:50.172235Z  INFO Registered 4 memory tools
2026-03-12T04:08:50.198716Z  INFO Loaded registry catalog entries for extension discovery count=14
2026-03-12T04:08:50.250884Z  INFO Registered 6 extension management tools
2026-03-12T04:08:50.250919Z  INFO Extension manager initialized with in-chat discovery tools
2026-03-12T04:08:50.310226Z  INFO Registered 4 skill management tools
2026-03-12T04:08:50.310691Z  INFO Tool registry initialized with 18 total tools
2026-03-12T04:08:50.320291Z  INFO Docker is available
2026-03-12T04:08:50.322049Z  INFO REPL mode enabled
2026-03-12T04:08:50.322346Z  INFO Orchestrator internal API listening on 0.0.0.0:50051
2026-03-12T04:08:50.325883Z  INFO Lifecycle hooks initialized bundled=1 plugin=0 workspace=0 outbound_       webhooks=0 errors=0
2026-03-12T04:08:50.326826Z  INFO Registered 6 job management tools
2026-03-12T04:08:50.328979Z  INFO Web UI: http://127.0.0.1:3000/

  ╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶

  ironclaw v0.12.0

  model     claude-sonnet-4-20250514  via anthropic
  database  postgres (connected)
  tools     24 registered
  features  embeddings (openai)  heartbeat (30m)  sandbox  routines  skills
  channels  repl  gateway

  gateway   http://127.0.0.1:3000/?token=

  ╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶╶

  /help for commands, /quit to exit

2026-03-12T04:08:50.329933Z  INFO Registered message tool
2026-03-12T04:08:50.339201Z  INFO Started channel: gateway
2026-03-12T04:08:50.339319Z  INFO Started channel: repl
2026-03-12T04:08:50.339610Z  INFO Registered 5 routine management tools
2026-03-12T04:08:50.341336Z  INFO Starting heartbeat loop with interval 1800s
2026-03-12T04:08:50.342285Z  INFO Routines enabled: cron ticker every 15s, max 10 concurrent
2026-03-12T04:08:50.342329Z  INFO Agent ironclaw ready and listening

You should store the gateway token value for your case. Use nginx to browse from internet like

http://your server-ip:3000/?token="your token value"

Example AI Agent Tasks

AI agents can automate complex workflows.

DevOps Automation

An AI agent can manage infrastructure tasks.

Examples:

• generate deployment scripts
• monitor system logs
• configure servers
• manage CI/CD pipelines

Software Development

Developers can use agents to assist coding tasks.

Examples:

• generate code snippets
• write documentation
• debug scripts
• review pull requests

Cloud Operations

Agents can interact with cloud APIs.

Examples:

• create cloud resources
• monitor infrastructure
• automate scaling workflows

Security Automation

Agents can assist with security monitoring.

Examples:

• analyze logs
• detect anomalies
• respond to incidents

AI Agents + Trusted Execution Environments

Ironclaw can integrate with Trusted Execution Environments (TEE).

This allows secure storage of secrets such as:

• API keys
• private keys
• blockchain credentials

Even if the AI model is compromised, the secrets remain protected.

Example Use Case: Infrastructure Automation

A DevOps engineer could ask the agent:

Deploy a Docker container running nginx
and expose port 80.

The agent may perform steps like:

Generate Docker run command
Execute shell commands
Verify service availability

Limitations of AI Agents

Although powerful, AI agents still have limitations:

• incorrect reasoning
• hallucinated outputs
• security risks if tools are unrestricted

For production environments it is recommended to:

• restrict agent permissions
• isolate execution environments
• review outputs before deployment

Conclusion

AI agents represent the next stage of infrastructure and software automation.

By combining frameworks like Ironclaw with large language models from OpenAI, developers can create systems capable of planning and executing complex tasks autonomously.

This technology is rapidly transforming areas such as:

• DevOps automation
• cloud infrastructure management
• software development workflows

Next Tutorials

Future tutorials on this blog will cover:

• building secure AI agents
• AI agents with Docker tools
• AI agents for DevOps automation
• integrating AI agents with cloud APIs

Tags: