Skip to main content
This guide covers both ways to run IronClaw: spin up a private instance on the Agent Hub with no installation, or install the binary on your own machine.
The fastest way to use IronClaw — no setup, no installation.

​
1. Sign in

Go to agent.near.ai and log in. Once logged in, create a new IronClaw agent. A private instance is provisioned for you.
You will need to provide an SSH key to connect to your private instance. If you don’t have one:
Add your SSH key to your device’s SSH agent before connecting:

​
2. Talk to your agent

Your agent is already running. You have two ways to interact: Web interface (recommended): Your Agent Dashboard shows a web gateway link — open it in your browser for the full IronClaw WebChat experience.
Terminal: Connect via SSH using the details shown in your dashboard, then start a chat session:
For one-shot commands:

​
3. Manage your agent

Use the Agent Dashboard to start, stop, or restart your instance. Updates are handled automatically by the platform.

​
Installing locally

For personal use on your own machine with full control.

​
1. Install IronClaw

Install the single binary:
On Windows, use the PowerShell installer:
Verify the install:

​
2. Run setup

Create your IronClaw home directory, provision a login token, and choose your inference provider:
When it finishes it prints a login link containing your token:
We recommend using NEAR AI as your inference provider for maximum privacy and security. See Inference Providers for the full list of supported providers.
Everything lives under ~/.ironclaw:Your master encryption key is stored in the OS keychain, not on disk. See Security.
In a script or CI, onboarding skips the interactive prompts and the service install:
Configure your provider separately with ironclaw models set-provider <provider> --model <model>, or by exporting the provider’s environment variables before running serve.Use --dry-run to see exactly what would be written without touching the filesystem.

​
3. Start the agent

Start the web interface:
By default it listens on 127.0.0.1:3000 — local only. Open the login link from the previous step in your browser, and you’ll land in the chat interface.
If port 3000 is taken, pass a different one:
Use --port 0 to let the operating system pick any free port.

​
4. Chat with your agent

Type a message in the chat and the agent will respond. From here you can also reach Projects, Jobs, Routines, and Settings from the sidebar. If you prefer the terminal, IronClaw has a REPL and a one-shot mode:

​
5. Keep it running

To have IronClaw start automatically in the background, install it as a system service (launchd on macOS, systemd on Linux):
Stop the foreground ironclaw serve first. The service runs serve too, so starting it while your terminal still holds the port fails with an address-already-in-use error.

​
6. Update IronClaw

Update to the latest release:

​
Next Steps

Now that your agent is running, connect a channel so you can reach it from a messaging app, and add extensions to give it more capabilities.

Channels

Connect your agent to Slack or Telegram.

Extensions

Give your agent access to external APIs and services.