Skip to main content

​
Installation

This guide covers installing OneClaw on development machines and deploying to edge devices like Raspberry Pi and other ARM-based hardware.

​
Prerequisites

​
Development machine

  • Rust toolchain: Version 1.85 or later with edition 2024 support
  • Build tools: Standard C/C++ compiler toolchain
  • Operating system: Linux, macOS, or Windows (Linux/macOS recommended for edge deployment)

​
Target edge device

  • Architecture: ARM64 (aarch64), x86_64, or RISC-V
  • RAM: Minimum 512MB (OneClaw uses less than 5MB)
  • Storage: Minimum 50MB for binary and data
  • Operating system: Linux-based (Raspbian, Ubuntu, Alpine, etc.)
OneClaw is optimized for Raspberry Pi 4+ but runs on any ARM64 or x86_64 Linux system.

​
Install Rust

If you don’t have Rust installed: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Verify installation: 
rustc --version
# Should show: rustc 1.85.0 or later
OneClaw requires Rust 1.85+ for edition 2024 features. Update with rustup update if needed.

​
Build from source

1

Clone repository

git clone https://github.com/nicekid1/oneclaw
cd oneclaw
2

Build release binary

cargo build --release
The optimized binary will be at target/release/oneclaw-core (~3.4MB).
First build downloads and compiles all dependencies. Subsequent builds are much faster.
3

Run tests (optional)

Verify the build with the test suite:
cargo test --workspace
All 550+ tests should pass.
4

Run locally

cargo run --release -p oneclaw-core

​
Cross-compile for edge devices

To deploy OneClaw on ARM devices like Raspberry Pi, cross-compile on your development machine. cross provides Docker-based cross-compilation with zero configuration:
1

Install cross

cargo install cross --git https://github.com/cross-rs/cross
2

Run build script

OneClaw includes a cross-compilation script:
./scripts/cross-build.sh 1.0.0
This builds for ARM64 (aarch64-unknown-linux-gnu) and creates deployment artifacts.
The script automatically handles Docker, target setup, and binary stripping.
3

Find binaries

Cross-compiled binaries are at:
target/aarch64-unknown-linux-gnu/release/oneclaw-core

​
Option B: Manual cross-compilation

For manual control or custom targets:
1

Add target

rustup target add aarch64-unknown-linux-gnu
For other architectures:
  • armv7-unknown-linux-gnueabihf (32-bit ARM)
  • x86_64-unknown-linux-gnu (Intel/AMD 64-bit)
  • riscv64gc-unknown-linux-gnu (RISC-V)
2

Install cross-compiler

On Ubuntu/Debian:
sudo apt-get install gcc-aarch64-linux-gnu
On macOS:
brew install filosottile/musl-cross/musl-cross
3

Build for target

cargo build --release --target aarch64-unknown-linux-gnu
Manual cross-compilation requires matching the target system’s libc version. Using cross avoids these compatibility issues.

​
Deploy to Raspberry Pi

Once you have a cross-compiled binary, deploy it to your edge device:
1

Copy files to device

Transfer the binary and deployment files:
scp target/release/oneclaw-core pi@raspberrypi:~/
scp deploy/oneclaw.service deploy/install.sh pi@raspberrypi:~/
Replace pi@raspberrypi with your device’s username and hostname.
2

SSH to device

ssh pi@raspberrypi
3

Run installer

The install script sets up OneClaw as a systemd service:
sudo ./install.sh 1.0.0
This:
  • Copies binary to /opt/oneclaw/bin/
  • Creates config directory at /opt/oneclaw/config/
  • Installs systemd service
  • Sets up proper permissions
4

Configure OneClaw

Edit the configuration file:
sudo nano /opt/oneclaw/config/default.toml
Add your provider settings and API keys:
[security]
deny_by_default = true

[provider]
primary = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 1024
temperature = 0.3
fallback = ["ollama"]

[provider.keys]
anthropic = "your-api-key-here"
Secure your config file: sudo chmod 600 /opt/oneclaw/config/default.toml
5

Start the service

sudo systemctl start oneclaw
Enable auto-start on boot:
sudo systemctl enable oneclaw
6

Verify deployment

Check service status:
sudo systemctl status oneclaw
Watch live logs:
journalctl -u oneclaw -f
You should see:
OneClaw v1.0.0 starting...
Security layer initialized (deny-by-default: enabled)
Provider configured: anthropic
Runtime ready in 0.79us

​
systemd service management

Manage the OneClaw service on your edge device: 
sudo systemctl start oneclaw

​
Platform-specific notes

​
Raspberry Pi

  • Recommended model: Pi 4 or later (4GB+ RAM preferred)
  • OS: Raspberry Pi OS (64-bit) or Ubuntu Server
  • Storage: Use SD card or SSD for better performance
  • Networking: Ensure stable internet for cloud LLM providers

​
Industrial gateways

  • OneClaw runs on standard x86_64 industrial PCs
  • Consider using Ollama locally to eliminate cloud dependencies
  • Use MQTT channel for sensor integration

​
Embedded ARM devices

  • Minimum 512MB RAM recommended
  • Test memory usage with metrics command
  • Consider disabling unused features to reduce footprint

​
Verify installation

Test your OneClaw installation:
1

Check binary size

ls -lh target/release/oneclaw-core
# Should show ~3.4MB
2

Run health check

After starting OneClaw:
oneclaw> health
All layers should report healthy status.
3

Test LLM provider

oneclaw> ask What is 2+2?
Should receive response from configured LLM.
4

Check metrics

oneclaw> metrics
Verify boot time (sub-10ms) and memory usage (under 5MB).

​
Uninstall

To remove OneClaw from an edge device: 
sudo ./deploy/uninstall.sh
This stops the service, removes files from /opt/oneclaw/, and uninstalls the systemd unit.
Uninstalling deletes all configuration and stored data. Back up important data first.

​
Troubleshooting

​
Build fails with “edition 2024 not found”

Update Rust to version 1.85+: 
rustup update stable

​
Cross-compilation linker errors

Use cross instead of manual cross-compilation: 
cargo install cross --git https://github.com/cross-rs/cross
./scripts/cross-build.sh 1.0.0

​
Service fails to start on Pi

Check logs for errors: 
journalctl -u oneclaw -n 50
Common issues:
  • Missing or invalid config file
  • Incorrect file permissions
  • Missing API keys

​
Binary too large

Ensure you’re building in release mode: 
cargo build --release
Release mode applies aggressive size optimizations (LTO, strip, opt-level=z).

​
Next steps

Configuration

Configure providers and features

Architecture

Understand the 6-layer design

Development

Build custom tools and channels

Deployment

Production deployment guide

Build docs developers (and LLMs) love

Get started for freeTalk to us