> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Running profClaw on Low-Memory Devices

> Install and run profClaw on Raspberry Pi Zero, $5 VPS, and other 512MB RAM devices

<Note>
  See [INSTALLATION.md](/docs/INSTALLATION.md) for the standard setup guide and [README](/docs/README.md) for a full feature overview.
</Note>

## The Problem

`npm install -g profclaw` on a 512MB device will get OOM-killed. Node's package installer is memory-hungry — it can spike past 400MB during dependency resolution alone.

You have three options depending on what you have available.

## Hardware Requirements

| Mode     | Minimum RAM | Swap Needed | Typical Device             |
| -------- | ----------- | ----------- | -------------------------- |
| **pico** | 256MB       | 256MB+      | Raspberry Pi Zero, \$5 VPS |
| **mini** | 512MB       | optional    | Raspberry Pi 3, \$10 VPS   |
| **pro**  | 2GB         | none        | Raspberry Pi 4+, \$20+ VPS |

***

## Option 1: Docker Pico Image (Recommended)

No npm install. Pull a pre-built image that runs in under 200MB of RAM.

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  ghcr.io/profclaw/profclaw:pico
```

Point to a remote Ollama instance on a beefier machine:

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  -e OLLAMA_BASE_URL=http://192.168.1.50:11434 \
  ghcr.io/profclaw/profclaw:pico
```

### Verify it works

```bash theme={null}
curl http://localhost:3000/health
```

A `200 OK` with `{"status":"ok"}` means the container is up and accepting requests.

### Connect an AI provider

Pass API keys as environment variables. Add whichever provider you use:

```bash theme={null}
docker run -d \
  --name profclaw \
  --restart unless-stopped \
  -p 3000:3000 \
  -v profclaw-data:/data \
  -e PROFCLAW_MODE=pico \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e GOOGLE_GENERATIVE_AI_API_KEY=AIza... \
  -e CEREBRAS_API_KEY=csk-... \
  -e OLLAMA_BASE_URL=http://192.168.1.50:11434 \
  ghcr.io/profclaw/profclaw:pico
```

You only need one provider. Set the one you have and skip the rest.

<Note>
  Pico mode skips authentication. There is no login screen and no user session required. Whoever can reach port 3000 can use the API. Do not expose the port publicly without a reverse proxy or firewall rule.
</Note>

***

## Option 2: Add Swap Before npm Install

Works on Raspberry Pi OS and most Debian-based systems. Gives the installer the memory headroom it needs.

```bash theme={null}
# Create a 1GB swap file
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Verify swap is active
free -h

# Now install
npm install -g profclaw

# Initialize and start
profclaw init
profclaw serve --mode pico
```

Make swap permanent across reboots:

```bash theme={null}
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```

<Note>
  On SD card devices (Pi Zero, Pi 3), heavy swap use will wear out your card faster. Use a USB SSD or a ramdisk-backed swap if running long-term.
</Note>

***

## Option 3: Cross-Install from Another Machine

Install profClaw on a machine with enough RAM, then copy the installed binary to your low-memory device.

On the build machine:

```bash theme={null}
# Install into a local directory (not global)
mkdir profclaw-bundle && cd profclaw-bundle
npm pack profclaw
npm install --prefix ./install profclaw

# Copy to target device
scp -r ./install pi@raspberrypi.local:/opt/profclaw
```

On the target device:

```bash theme={null}
# Run directly from the copied install
/opt/profclaw/node_modules/.bin/profclaw init
/opt/profclaw/node_modules/.bin/profclaw serve --mode pico
```

Optionally symlink it:

```bash theme={null}
sudo ln -s /opt/profclaw/node_modules/.bin/profclaw /usr/local/bin/profclaw
```

***

## Pico Mode: What Works, What Doesn't

### Works in pico

* Agent engine (full reasoning loop)
* 72 core tools (file, git, shell, HTTP, memory, cron)
* CLI chat (`profclaw chat`)
* REST API on port 3000
* Cron jobs and scheduled tasks
* One chat channel (your choice: Slack, Telegram, Discord, etc.)

### Not available in pico

| Feature                        | Why                               |
| ------------------------------ | --------------------------------- |
| Web UI dashboard               | Removed to save \~80MB at idle    |
| Redis queue                    | Replaced with SQLite-backed queue |
| Browser/Playwright tools       | Chromium won't fit in memory      |
| Multiple simultaneous channels | Single channel limit              |
| Real-time multi-user sessions  | No WebSocket broadcast layer      |

Switch to mini mode when you have 512MB+:

```bash theme={null}
profclaw serve --mode mini
```

Mini adds the web UI and multi-channel support. Pro adds Redis, browser tools, and full concurrency.

***

## Using a Separate Ollama Instance

Running inference on a Pi Zero is impractical. Point profClaw at an Ollama instance running on another machine on your network.

```bash theme={null}
# In .env or environment
OLLAMA_BASE_URL=http://192.168.1.50:11434
```

Or in `settings.yml`:

```yaml theme={null}
ai:
  provider: ollama
  baseUrl: http://192.168.1.50:11434
  model: llama3.2:3b
```

The Pi Zero acts as the agent runtime — tool execution, memory, scheduling, API surface — while a beefier machine handles inference. Works well with a Pi 5 or an old laptop as the Ollama host.

Verify the connection:

```bash theme={null}
profclaw doctor
```

The doctor check will confirm the Ollama endpoint is reachable and the model is loaded.

***

## Troubleshooting

### Container won't start

Check the logs before anything else:

```bash theme={null}
docker logs profclaw
```

Common causes: port 3000 already in use, missing `PROFCLAW_MODE`, or a bad volume mount path. The logs will point to the specific error.

### OOM during npm install (Options 2 and 3)

If the install gets killed mid-way, you do not have enough memory headroom. Use the swap method from Option 2 first, then retry:

```bash theme={null}
sudo swapon /swapfile
npm install -g profclaw
```

If you already added swap and it still fails, the swap file may be too small. Extend it:

```bash theme={null}
sudo swapoff /swapfile
sudo fallocate -l 2G /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```

### "No AI provider configured"

profClaw requires at least one AI provider key at startup. Set the env var for the provider you want to use:

```bash theme={null}
# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
export GOOGLE_GENERATIVE_AI_API_KEY=AIza...

# Cerebras
export CEREBRAS_API_KEY=csk-...

# Local Ollama
export OLLAMA_BASE_URL=http://192.168.1.50:11434
```

For Docker, pass it with `-e` as shown in the install command above. For the npm install path, add it to your `.env` file in the profClaw data directory.

### Can't reach the API

1. Check the container or process is actually running:

```bash theme={null}
docker ps | grep profclaw
```

2. Confirm the port binding:

```bash theme={null}
docker port profclaw
```

3. Try curl from inside the container to rule out a network issue:

```bash theme={null}
docker exec profclaw curl -s http://localhost:3000/health
```

If that works but `curl http://localhost:3000/health` from your host does not, the problem is the port binding or a local firewall rule, not profClaw itself.

***

For the standard installation path on a full-spec machine, see the [main installation guide](/docs/INSTALLATION.md).