# IronClaw: a local-first agent OS with a WASM sandbox and encrypted secrets

> IronClaw is a Rust agent runtime from nearai that keeps credentials out of tool code, runs untrusted tools in WebAssembly, and installs from a release tag. It is a strong fit for engineers who want an assistant they can audit, and a poor fit for anyone who wants a hosted service with no local state.

**nearai/ironclaw** — IronClaw is an Agent OS focused on privacy, security and extensibility.

- Repository: https://github.com/nearai/ironclaw
- Website: https://www.ironclaw.com
- Stars: 12,630 · Forks: 1,481
- Language: Rust
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/nearai-ironclaw

## The problem IronClaw targets: an assistant that can act without leaking your keys

Most agent runtimes hand a language model a set of tools and an API key and hope for the best. IronClaw inverts that. The README states the principle directly: your data stays local, encrypted, and under your control, with no hidden telemetry. The repository is Apache-2.0 and Rust, and the workspace layout in Cargo.toml shows how far the separation goes: secrets, network, authorization, approvals, trust and capabilities are each their own crate under crates/kernel and crates/substrates, rather than flags inside one binary.

The target reader is an engineer who wants to run an assistant on their own hardware and still connect it to Slack, Telegram, HTTP webhooks or a browser UI. The pitch is not raw capability. It is that the capability arrives with a boundary around it. If you have ever pasted a personal access token into a third-party agent and then wondered where it went, that is the scenario this project is built for.

## How the runtime is put together: kernel, lanes, and an extension host

The Cargo.toml workspace members read like a map. crates/kernel holds the host runtime, runtime policy, authorization, approvals, resources, trust and turns. crates/lanes holds the execution lanes: ironclaw_wasm, ironclaw_wasm_limiter, ironclaw_sandbox and ironclaw_mcp. crates/extensions holds the registry, host and manager for extensions. crates/events splits the event log, streams, store and projections into four crates. Memory is a domain (ironclaw_memory) with two extension packages, memory-native and mem0.

That structure tells you the data flow. A turn enters through a product ingress crate, is evaluated against policy and authorization, then dispatched into a lane. Tools that are not trusted run in the WASM lane under a limiter; containerized work goes through the sandbox lane; external capabilities come in over MCP. Events are written to a log and projected for query. Credentials live in crates/substrates/ironclaw_secrets and, per the README, are injected at the host boundary with leak detection rather than handed to the tool. The README also lists prompt injection defense through pattern detection, content sanitization and policy enforcement, and endpoint allowlisting so HTTP requests only reach explicitly approved hosts and paths.

The honest read: this is a large workspace with many small crates, which buys separation of concerns and costs you a long build. Source builds require Rust 1.96+ and Node.js 22+ with Corepack/pnpm, which is a heavier toolchain than a single-binary agent.

## Installing IronClaw and running your first onboard

The README points at the Releases page and asks you to pick an ironclaw-v* tag, replacing X.Y.Z with the version including any prerelease suffix. The shell installer covers macOS, Linux and Windows/WSL. The curl call is piped to sh, so read the script first if you are installing on a machine you care about.

```bash
IRONCLAW_RELEASE_TAG=ironclaw-vX.Y.Z
curl --proto '=https' --tlsv1.2 -LsSf \
  "https://github.com/nearai/ironclaw/releases/download/${IRONCLAW_RELEASE_TAG}/ironclaw-installer.sh" | sh
```

After the installer finishes, run the guided setup. The README says onboard asks you to choose an LLM provider, enter its API key at a hidden prompt, and accept the default model or type another one. It then provisions local configuration, the encrypted credential store and a WebUI login token. On macOS and Linux it also installs and starts the background service and prints a link that opens the WebUI.

```bash
ironclaw onboard
```

Check what you got with status, which reports the service state and prints the login link again. If you are on Windows, the README says to start the WebUI in the foreground with ironclaw serve instead of relying on the service.

```bash
ironclaw status
```

State lands under $HOME/.ironclaw/reborn by default. To inspect the rest, the README gives three read-only commands: ironclaw status, ironclaw models status and ironclaw config list. Switching providers later means selecting the route and then storing the key through the hidden prompt, because secret values never accept a positional argument.

```bash
ironclaw models set-provider openai --model gpt-5-mini
ironclaw config set openai.api_key
```

One behaviour to internalize early: configuration writes never restart the service automatically. After a change that affects the running service, run ironclaw service restart. The README points at ironclaw config set --help for the full list of supported keys. Channels such as Slack and Telegram are the exception to the CLI path: they have no configuration-file settings and no CLI enablement key, so you install the extension and finish setup on the WebUI Extensions page.

## Where IronClaw gets awkward: sandbox limits, service restarts, and platform gaps

The WASM sandbox is the selling point and also the constraint. A tool that needs a native library, a long-lived socket, or filesystem access outside what the capability model grants cannot simply be dropped in as a WASM package. The README describes dynamic tool building, where you describe what you need and IronClaw builds it as a WASM tool, but it does not promise that arbitrary existing code becomes a tool unchanged. If your integration is a Python script with a pile of dependencies, the sandbox lane or an MCP server is the more realistic route.

The service model is the second friction point. On macOS and Linux onboard installs and starts a background service, and config changes do not restart it. That is a deliberate choice, since silently restarting a running agent mid-turn would be worse, but it means a two-step workflow for every change: set the value, then restart. Windows users do not get that path at all in the documented flow; they run the WebUI in the foreground with ironclaw serve.

Finally, the README does not document rollback for a configuration change or a version downgrade. The repository has a CHANGELOG.md and release tags, and release-plz.toml is present at the top level, so version history exists, but the README itself is silent on how to revert. Treat that as an open question to answer before you put this in front of other people.

## IronClaw compared with a plain MCP client or a hosted assistant

The closest comparison is a generic MCP client wired to a chat UI. That setup connects to Model Context Protocol servers and gives the model tools, but the credential handling is usually the client's problem: keys sit in an environment file or a config the model can read. IronClaw also speaks MCP through the ironclaw_mcp lane, so it is not an either/or on capability. The difference is what surrounds the call: a secrets substrate that injects at the host boundary, an authorization and approvals layer, an endpoint allowlist, and an event log with projections. You are trading setup time for a runtime that records and constrains what happened.

The other comparison is a hosted assistant. There, you get zero local state and someone else's uptime. IronClaw is the inverse: the README is explicit that information is stored locally and encrypted, and that there is no hidden telemetry. That is only an advantage if you actually want to operate the thing. The Dockerfile and docker-compose.yml in the repository show a Postgres-backed path (pgvector/pgvector:pg16, database ironclaw on port 5432) for the standalone Reborn CLI HTTP service, and the Dockerfile comments describe Railway profiles such as hosted-single-tenant, so a server deployment is contemplated. But the quick start is a per-machine install, not a signup.

## Licence, maintenance and the cost of keeping up

The repository is Apache-2.0 and also ships LICENSE-MIT, so the code is dual-licensed in practice; the GitHub metadata lists Apache-2.0 as the primary. For most internal use that is permissive, but if you modify and redistribute IronClaw, read both files rather than assuming one governs. Nothing here is legal advice.

On maintenance, the last push was on 2026-08-28, and the most recent release is ironclaw-v1.4.0 from 2026-08-27, preceded by a release candidate on 2026-08-26 and ironclaw-v1.3.0 on 2026-08-19. The project is not archived. The upgrade cost is real: this is a Cargo workspace with dozens of member crates, so a source build compiles a large dependency graph and needs Rust 1.96+ plus Node.js 22+ with Corepack/pnpm. If you install from a release tag instead, you still own the migration between tags, and the README does not describe a downgrade path. Budget for reading CHANGELOG.md before each bump.

## Conclusion

Adopt IronClaw if you want an agent runtime where the credential store, the sandbox boundary and the network allowlist are all inspectable on your own machine, and you are willing to run a background service and restart it after config changes. Do not adopt it if you need a hosted assistant with no local footprint, or if your tools cannot be expressed as WASM packages or MCP servers. Before committing, verify that your chosen LLM backend is listed in .env.example, that your platform has an installer on the Releases page, and that you have read how ironclaw config set handles secret values, because secrets are never accepted as positional arguments.

## FAQ

### How do I install IronClaw?

Pick an ironclaw-v* tag on the Releases page, set IRONCLAW_RELEASE_TAG to that tag, and pipe the ironclaw-installer.sh script from the release download URL into sh. Windows users can instead run the .msi installer or the PowerShell installer script. Source builds need Rust 1.96+ and Node.js 22+ with Corepack/pnpm.

### How do I set up IronClaw after installing it?

Run ironclaw onboard, choose an LLM provider, enter its API key at the hidden prompt, and accept the default model or enter another one. Onboarding provisions local configuration, the encrypted credential store and a WebUI login token, and on macOS and Linux it starts the background service and prints a link to the WebUI.

### How do I use IronClaw?

After onboarding, use ironclaw status to check the service and print the WebUI login link again, and ironclaw config list to inspect settings. Channels such as Slack and Telegram are enabled by installing the extension and completing setup on the WebUI Extensions page, since they have no CLI enablement key.

### What is IronClaw AI?

It is an agent OS written in Rust by nearai, described in its README as a secure personal AI assistant that stores data locally and encrypted. It combines a WASM sandbox for untrusted tools, an encrypted credential store, prompt injection defenses and an endpoint allowlist.

## Sources

- [Official documentation](https://www.ironclaw.com)
- [Official README](https://github.com/nearai/ironclaw#readme)
- [Project repository](https://github.com/nearai/ironclaw)
- [Release notes](https://github.com/nearai/ironclaw/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nearai-ironclaw