ironclaw/docs/quickstart.mdx

---
title: Quickstart
description: Create your first Agent in minutes
icon: rocket
---

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.

---

## Agent Hub (Recommended)

The fastest way to use IronClaw — no setup, no installation.

### 1. Sign in

Go to [agent.near.ai](https://agent.near.ai/) and log in. Once logged in, create a new IronClaw agent. A private instance is provisioned for you.

<Accordion title="SSH Key">
You will need to provide an SSH key to connect to your private instance. If you don't have one:

```bash
ssh-keygen -t rsa -b 4096 -C "you@example.com"
cat ~/.ssh/id_rsa.pub
```

</Accordion>

<Accordion title="Issues Connecting?">
Add your SSH key to your device's SSH agent before connecting:

```bash
ssh-add ~/.ssh/id_rsa
```

</Accordion>

### 2. Talk to your agent

Your agent is already running. You have two ways to interact:

**Web interface (recommended):** Your [Agent Dashboard](https://agent.near.ai/) shows a web gateway link — open it in your browser for the full IronClaw WebChat experience.

```
https://<instance-id>.agents.near.ai
```

**Terminal:** Connect via SSH using the details shown in your dashboard, then start a chat session:

```bash
ssh -p <PORT> <username>@<host>
ironclaw chat
```

For one-shot commands:

```bash
ironclaw run -m "Summarize my last three emails"
```

### 3. Manage your agent

Use the [Agent Dashboard](https://agent.near.ai/) 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:

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
```

On Windows, use the PowerShell installer:

```powershell
irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex
```

Verify the install:

```bash
ironclaw --version
```

### 2. Run setup

Create your IronClaw home directory, provision a login token, and choose your inference provider:

```bash
ironclaw onboard
```

When it finishes it prints a login link containing your token:

```
login_link: http://127.0.0.1:3000/login?token=<your-token>
```

<Note>
We recommend using [NEAR AI](https://cloud.near.ai/) as your inference provider for
maximum privacy and security. See [Inference Providers](/capabilities/llm-providers) for
the full list of supported providers.
</Note>

<Accordion title="What onboarding creates">

Everything lives under `~/.ironclaw`:

| File | Purpose |
| --- | --- |
| `config.toml` | Your configuration — profile, identity, model selection |
| `providers.json` | The catalog of inference providers available to this install |
| `webui-token` | Bearer token used by the web interface |
| `.onboard-completed.json` | Marks setup as complete |

Your master encryption key is stored in the OS keychain, not on disk. See
[Security](/security).

</Accordion>

<Accordion title="Running setup non-interactively">

In a script or CI, onboarding skips the interactive prompts and the service install:

```bash
ironclaw onboard --no-service < /dev/null
```

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.

</Accordion>

### 3. Start the agent

Start the web interface:

```bash
ironclaw serve
```

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.

<Accordion title="⚠️ Port already in use">

If port 3000 is taken, pass a different one:

```bash
ironclaw serve --port 3100
```

Use `--port 0` to let the operating system pick any free port.

</Accordion>

<Accordion title="Lost your login link?">

Print your configuration paths and read the token back:

```bash
ironclaw config path
cat ~/.ironclaw/webui-token
```

Then visit `http://127.0.0.1:3000/login?token=<token>`.

</Accordion>

### 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:

```bash
ironclaw repl
ironclaw run -m "Summarize my last three emails"
```

### 5. Keep it running

To have IronClaw start automatically in the background, install it as a system service
(launchd on macOS, systemd on Linux):

<Warning>
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.
</Warning>

```bash
# Ctrl-C the foreground server, then:
ironclaw service install
ironclaw service start
ironclaw service status
```

### 6. Update IronClaw

Update to the latest release:

```bash
ironclaw-update
```

---

## Next Steps

Now that your agent is running, connect a [channel](/channels/overview) so you can reach
it from a messaging app, and add [extensions](/extensions/overview) to give it more
capabilities.

<CardGroup cols={2}>
  <Card title="Channels" icon="plug" href="/channels/overview">
    Connect your agent to Slack or Telegram.
  </Card>

  <Card title="Extensions" icon="wrench" href="/extensions/overview">
    Give your agent access to external APIs and services.
  </Card>
</CardGroup>