V1Claw

Your 24/7 Personal AI Assistant — Like Jarvis, but open source.

V1Claw is a self-hosted AI assistant that runs on your Mac, Linux PC, Windows machine, or Android phone via Termux. Connect any LLM (Claude, GPT, Gemini, or local models), talk to it through voice or text, and let it control your device — read files, run commands, browse the web, take photos, send messages, and more.

One binary. No cloud dependency. Your data stays on your machine.

Features

🧠 13 LLM Providers

Connect to any AI model — paid APIs or self-hosted:

Provider	Type	Models
Anthropic	Cloud API	Claude 4, Claude 3.5, etc.
OpenAI	Cloud API	GPT-5, GPT-4, etc.
Google Gemini	Cloud API	Gemini 2.x, etc.
Groq	Cloud API	LLaMA, Mixtral (fast inference)
OpenRouter	Cloud API	100+ models via single API
DeepSeek	Cloud API	DeepSeek V3, Coder
NVIDIA	Cloud API	NIM models
Moonshot	Cloud API	Kimi
Zhipu	Cloud API	GLM-4
Ollama	Local	Any GGUF model on your machine
vLLM	Local	Self-hosted inference server
GitHub Copilot	Cloud API	Via Copilot subscription
Any OpenAI-compatible API	REST API	Custom endpoints

🎤 Voice I/O Pipeline

Talk to V1Claw like Jarvis:

Microphone recording — continuous listening with configurable backends
Speech-to-Text — powered by Groq Whisper (fast, accurate)
Text-to-Speech — OpenAI TTS or Edge TTS (free)
Wake word detection — "Hey V1Claw" or custom phrases
Push-to-talk mode — manual recording trigger
Works on desktop (arecord/ffplay) and Android (termux-microphone-record/termux-media-player)

📷 Vision & Camera

Capture photos from camera (desktop or Termux)
Analyze images with vision-capable LLMs
Screenshot capture and OCR
Object detection support

📱 10 Communication Channels

Run V1Claw as a bot on any platform:

Channel	Protocol
Telegram	Bot API
Discord	Bot gateway
Slack	Socket Mode
WhatsApp	WebSocket bridge
LINE	Messaging API
DingTalk	Stream SDK
Feishu/Lark	Event subscription
QQ	Official bot API
OneBot	WebSocket (v11)
MaixCam	TCP (IoT devices)

🛠️ 14 Built-in Tools

The AI can use these tools autonomously:

Tool	Description
`read_file`	Read file contents
`write_file`	Create/overwrite files
`edit_file`	Surgical text replacements
`append_file`	Append to files
`list_dir`	Browse directories
`exec`	Run shell commands
`web_search`	Search the web (Brave/Perplexity)
`web_fetch`	Fetch and read web pages
`message`	Send messages to channels
`cron`	Schedule recurring tasks
`subagent`	Spawn sub-agents for complex tasks
`spawn`	Run async background tasks
`spi`	SPI device communication (Linux)
`i2c`	I2C device communication (Linux)

📱 Android/Termux Integration

Full hardware access on Android via Termux:API:

🎤 Microphone recording
📷 Camera capture
🔊 Text-to-speech
📍 GPS location
📋 Clipboard read/write
💡 Flashlight control
📳 Vibration
📱 SMS send/receive
📞 Phone calls
🔋 Battery status
📶 WiFi info
🔔 Notifications
🔊 Volume control

🔒 Security

Deny-by-default permissions — camera, microphone, SMS, phone, location, clipboard, sensors each require explicit opt-in
Permissions freeze after startup — the AI cannot grant itself new permissions at runtime
Shell command filtering — 26 deny patterns block dangerous commands (reverse shells, rc file modification, encoding tricks)
SSRF protection — web fetch blocks localhost, private networks, cloud metadata endpoints
Path traversal protection — skill install/load validates against directory escape
API authentication — configurable API key with constant-time comparison
Hardened file permissions — all config/state files use 0600/0700
Non-root Docker — container runs as unprivileged user
Content boundary markers — mitigates prompt injection from user-provided files

⏰ Proactive & Scheduled Tasks

Cron scheduling — schedule recurring tasks (reminders, checks, reports)
Proactive engine — AI can initiate actions based on context
Heartbeat monitoring — system health checks

🧩 Skills System

Extend V1Claw with installable skills:

Built-in skills included
Install community skills from URLs
Skills are sandboxed markdown agent configurations

Setup Guide

Pick your device. Follow the steps. You'll have a working AI assistant in under 10 minutes.

You need one thing before you start: an API key from any AI provider. The easiest free option is Google Gemini — get a key at aistudio.google.com/apikey. Other options: OpenAI, Anthropic, Groq, OpenRouter.

📱 Android (Termux)

Click to expand — full step-by-step Android setup

Step 1: Install two apps from F-Droid

You need two apps. Install both from F-Droid (NOT from Play Store — the Play Store versions are outdated and broken):

Termux — a Linux terminal for Android
Termux:API — lets V1Claw use your phone's mic, camera, GPS, etc.

💡 If you don't have F-Droid, download it first from f-droid.org.

Step 2: Grant permissions to Termux:API

Open your phone Settings → Apps → Termux:API → Permissions and turn on:

✅ Microphone
✅ Camera
✅ Location (optional)

Step 3: Install developer tools in Termux

Open Termux and type these commands one at a time. Press Enter after each one:

pkg update

It may ask "Do you want to continue?" — type y and press Enter.

pkg upgrade -y

pkg install -y git golang make termux-api

This installs Git, Go (the programming language), Make, and the Termux API tools. It takes about 2-3 minutes.

Step 4: Download V1Claw

git clone https://github.com/amit-vikramaditya/V1Claw.git

cd V1Claw

Step 5: Build V1Claw

make build

This compiles V1Claw into a single file. It takes 2-5 minutes on a phone. When it finishes, you'll see a file at build/v1claw-android-arm64.

💡 The Makefile auto-detects Termux and handles everything for you. No extra flags needed.

Step 6: Run first-time setup

./build/v1claw-android-arm64 onboard

The setup wizard will ask you to:

Pick your AI provider (Gemini is free and recommended)
Paste your API key

That's it — your config is ready at ~/.v1claw/config.json.

Don't have an API key yet? Press Enter to pick Gemini, then get a free key at aistudio.google.com/apikey. You can re-run onboard anytime, or edit the config manually with nano ~/.v1claw/config.json.

Step 7: Test it!

./build/v1claw-android-arm64 agent -m "Hello! What can you do?"

You should see the AI respond. If it does — congratulations, V1Claw is working on your phone! 🎉

Step 8: Start chatting

./build/v1claw-android-arm64 agent

This opens an interactive chat. Type anything and press Enter. Type exit or press Ctrl+C to quit.

Step 9: Enable phone hardware (optional)

Want V1Claw to use your mic, camera, or read notifications? Edit the config again:

nano ~/.v1claw/config.json

Add a "permissions" section (you can turn each feature on or off individually):

{
  "permissions": {
    "microphone": true,
    "camera": true,
    "clipboard": true,
    "notifications": true,
    "location": false,
    "sms": false,
    "phone_calls": false,
    "sensors": false,
    "shell_hardware": true
  }
}

🔒 Every feature is OFF by default. Only turn on what you need. You can change these anytime by editing the config and restarting.

Step 10: Run V1Claw 24/7 in the background (optional)

nohup ./build/v1claw-android-arm64 gateway > v1claw.log 2>&1 &

This runs V1Claw as a background service that keeps working even if you close Termux.

To check if it's running:

curl http://127.0.0.1:18790/health

To see what it's doing:

tail -f v1claw.log

To stop it:

kill $(cat v1claw.pid 2>/dev/null || pgrep v1claw)

🍎 macOS

Click to expand — full step-by-step macOS setup

Step 1: Install Go (if you don't have it)

Open Terminal (press Cmd+Space, type "Terminal", press Enter).

Check if Go is installed:

go version

If it says "command not found", install it:

# Using Homebrew (recommended)
brew install go

# Or download from https://go.dev/dl/

Also make sure you have Git and Make (these come pre-installed on most Macs):

git --version
make --version

Step 2: Download V1Claw

git clone https://github.com/amit-vikramaditya/V1Claw.git
cd V1Claw

Step 3: Build

make build

The binary will appear at build/v1claw-darwin-arm64 (Apple Silicon) or build/v1claw-darwin-amd64 (Intel Mac).

Step 4: Run first-time setup

./build/v1claw-darwin-* onboard

The setup wizard will ask you to pick a provider and enter your API key. Your config is ready immediately.

Step 5: Test it

./build/v1claw-darwin-* agent -m "Hello! Tell me a fun fact."

If you see a response — it's working! 🎉

Step 6: Interactive chat

./build/v1claw-darwin-* agent

Step 7: Run as a 24/7 service (optional)

# Quick background mode
nohup ./build/v1claw-darwin-* gateway > v1claw.log 2>&1 &

# Or install to your PATH and use it anywhere
make install
v1claw gateway

🐧 Linux

Click to expand — full step-by-step Linux setup

Step 1: Install Go, Git, and Make

Ubuntu/Debian:

sudo apt update && sudo apt install -y golang git make

Fedora:

sudo dnf install -y golang git make

Arch Linux:

sudo pacman -S go git make

Verify Go is installed:

go version

Step 2: Download V1Claw

git clone https://github.com/amit-vikramaditya/V1Claw.git
cd V1Claw

Step 3: Build

make build

The binary will appear at build/v1claw-linux-amd64 or build/v1claw-linux-arm64.

Step 4: Run first-time setup

./build/v1claw-linux-* onboard

The setup wizard will ask you to pick a provider and enter your API key. Your config is ready immediately.

Step 5: Test it

./build/v1claw-linux-* agent -m "Hello! What can you do?"

Step 6: Run as a 24/7 system service (optional)

# Install the binary
make install

# Create a systemd service
sudo tee /etc/systemd/system/v1claw.service << 'EOF'
[Unit]
Description=V1Claw AI Assistant
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/.local/bin/v1claw gateway
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Replace YOUR_USERNAME with your actual username, then:
sudo systemctl daemon-reload
sudo systemctl enable --now v1claw

# Check status
sudo systemctl status v1claw

🪟 Windows

Click to expand — full step-by-step Windows setup

Step 1: Install Go and Git

Download and install Go from go.dev/dl — pick the Windows .msi installer
Download and install Git from git-scm.com
Download and install Make via GnuWin32 or use choco install make if you have Chocolatey

Open Command Prompt or PowerShell and verify:

go version
git --version

Step 2: Download V1Claw

git clone https://github.com/amit-vikramaditya/V1Claw.git
cd V1Claw

Step 3: Build

make build

Or if Make doesn't work on Windows:

go build -o build/v1claw.exe ./cmd/v1claw

Step 4: Run first-time setup

build\v1claw.exe onboard

The setup wizard will ask you to pick a provider and enter your API key. Your config is ready immediately.

Step 5: Test it

build\v1claw.exe agent -m "Hello! What can you do?"

Step 6: Interactive chat

build\v1claw.exe agent

🐳 Docker (any platform)

Click to expand — Docker setup

If you have Docker installed, this is the fastest way:

# Clone the project
git clone https://github.com/amit-vikramaditya/V1Claw.git
cd V1Claw

# Copy the example config and edit it
cp config/config.example.json config/config.json
nano config/config.json   # Add your provider API key

# Run a one-shot query
docker compose run --rm v1claw-agent -m "Hello V1Claw!"

# Or run as a 24/7 background service
docker compose --profile gateway up -d

🔗 Cross-Compile for Another Device

Have a fast PC and want to build V1Claw for a different device (e.g., build on your Mac for your Android phone)?

# On your PC:
git clone https://github.com/amit-vikramaditya/V1Claw.git
cd V1Claw

# Build for Android (ARM64)
GOOS=linux GOARCH=arm64 make build

# Build for Linux server (x86_64)
GOOS=linux GOARCH=amd64 make build

# Build for Windows
GOOS=windows GOARCH=amd64 make build

# Build for Raspberry Pi
GOOS=linux GOARCH=arm GOARM=7 make build

Then transfer the binary to your target device (via USB, scp, adb push, or any file sharing method) and follow from Step 4 of the relevant guide above.

🌐 Multi-Device Setup (Tailscale)

Want V1Claw on multiple devices sharing one brain? Use Tailscale (free for personal use):

Install Tailscale on all your devices

Run V1Claw gateway on your main machine (server/desktop):

# Edit config — set gateway.host to "0.0.0.0" and enable the API:
# "v1_api": {"enabled": true, "addr": ":18791", "api_key": "your-secret-key"}
v1claw gateway

From any other device on your Tailscale network:

# Interactive mode — full chat with the gateway's brain
v1claw client --server your-server.tail1234.ts.net:18791 --api-key your-secret-key

# One-shot message
v1claw client -s your-server.tail1234.ts.net:18791 -k your-secret-key -m "Hello from my phone"

# Or use the REST API directly
curl http://your-server.tail1234.ts.net:18791/api/v1/chat \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"message": "Hello from my phone"}'

The client auto-detects local hardware (camera, mic, screen) and registers it with the gateway. When the AI needs to take a photo but the server has no camera, it routes the request to your phone's camera automatically.

Configuration Reference

See config/config.example.json for the full configuration schema.

Key Sections

Section	Purpose
`agents`	Agent name, model, temperature, max tokens, workspace
`providers`	LLM provider credentials and endpoints
`channels`	Telegram/Discord/Slack/etc. bot tokens
`tools`	Web search API keys (Brave, Perplexity)
`voice`	Voice I/O settings, TTS provider, wake phrases
`permissions`	Per-feature hardware access toggles
`gateway`	Host, port, API key
`heartbeat`	System health monitoring interval

Permissions

Each hardware feature can be individually enabled or disabled. All are off by default:

Permission	What It Controls
`camera`	Photo capture, vision analysis
`microphone`	Audio recording, voice input
`sms`	Send/receive text messages
`phone_calls`	Initiate phone calls
`location`	GPS coordinates
`clipboard`	Read/write clipboard
`sensors`	Device sensors (accelerometer, etc.)
`shell_hardware`	Hardware shell commands (Termux)
`notifications`	System notifications
`screen`	Screenshot capture

Permissions are frozen after startup — the AI cannot escalate its own access at runtime. Change permissions by editing your config and restarting.

CLI Commands

v1claw onboard              # First-time setup
v1claw agent                # Interactive chat
v1claw agent -m "query"     # One-shot query
v1claw gateway              # Start 24/7 daemon
v1claw client -s host:port  # Connect to a remote gateway
v1claw auth login           # Authenticate
v1claw auth status          # Check auth status
v1claw status               # Show system status
v1claw cron                 # Manage scheduled tasks
v1claw skills list          # List installed skills
v1claw skills install <url> # Install a skill
v1claw version              # Show version

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        V1Claw                               │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │ Channels │  │  Voice   │  │  Vision  │  │   Tools    │  │
│  │----------│  │----------│  │----------│  │------------│  │
│  │ Telegram │  │ Mic→STT  │  │ Camera   │  │ Files      │  │
│  │ Discord  │  │ TTS→Spk  │  │ Screen   │  │ Shell      │  │
│  │ Slack    │  │ Wake Word│  │ OCR      │  │ Web        │  │
│  │ WhatsApp │  │          │  │          │  │ Cron       │  │
│  │ LINE     │  │          │  │          │  │ Subagent   │  │
│  │ 5 more.. │  │          │  │          │  │ I2C/SPI    │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
│       │              │              │              │         │
│       └──────────────┴──────┬───────┴──────────────┘         │
│                             │                                │
│                      ┌──────┴──────┐                         │
│                      │ Agent Loop  │                         │
│                      │ (pkg/agent) │                         │
│                      └──────┬──────┘                         │
│                             │                                │
│                      ┌──────┴──────┐                         │
│                      │  Providers  │                         │
│                      │-------------│                         │
│                      │ Claude      │                         │
│                      │ GPT         │                         │
│                      │ Gemini      │                         │
│                      │ Ollama      │                         │
│                      │ 9 more..    │                         │
│                      └─────────────┘                         │
│                                                             │
│  ┌──────────┐  ┌────────────┐  ┌──────────┐  ┌───────────┐ │
│  │ Perms    │  │ Termux API │  │  Skills  │  │ Security  │ │
│  │ (deny    │  │ (Android   │  │ (extend- │  │ (shell    │ │
│  │ default) │  │  hardware) │  │  able)   │  │  guards)  │ │
│  └──────────┘  └────────────┘  └──────────┘  └───────────┘ │
└─────────────────────────────────────────────────────────────┘

Roadmap — Towards a True 24/7 AI Assistant

V1Claw works today as a powerful single-device assistant. Here's what's next to make it a full Jarvis:

✅ Done

🚧 In Progress

Always-on wake word — persistent low-power listening mode

🔮 Future

Local STT/TTS — fully offline voice without cloud APIs
Smart home integration — control IoT devices
Context-aware proactive suggestions — "you have a meeting in 10 minutes"
End-to-end encryption for multi-device communication
Web dashboard with real-time status and conversation history
Plugin marketplace for community-built skills

Troubleshooting

Problem	Solution
`command not found: go`	Install Go — see setup guide for your platform above
`command not found: make`	Linux: `sudo apt install make` / Mac: `xcode-select --install` / Windows: `choco install make`
`permission denied`	Run `chmod +x build/v1claw-*` to make the binary executable
Build fails with "out of memory"	Close other apps. On Android, phones have limited RAM — try closing background apps
`termux-microphone-record: not found`	Install Termux:API app from F-Droid AND run `pkg install termux-api` in Termux
API key error / "unauthorized"	Double-check your API key in `~/.v1claw/config.json`. Make sure there are no extra spaces
`connection refused` on port 18790	The gateway isn't running. Start it with `v1claw gateway` first
AI doesn't use my camera/mic	Enable the permission in config: `"microphone": true` or `"camera": true` and restart
`go version` shows old version	V1Claw needs Go 1.25+. Update Go from go.dev/dl

Contributing

V1Claw is an ambitious project to build a truly personal, open-source AI assistant that rivals commercial offerings like Alexa, Siri, or Google Assistant — but with full privacy, no cloud lock-in, and the power of frontier LLMs.

We're looking for developers to help build the future of personal AI:

🧠 AI/ML engineers — local model integration, fine-tuning, RAG pipelines
🎤 Audio/voice engineers — wake word detection, noise cancellation, streaming STT
📱 Mobile developers — native Android/iOS clients, Wear OS support
🏠 IoT/smart home developers — Home Assistant, Matter/Thread integration
🔒 Security researchers — sandboxing, formal verification, threat modeling
🌐 Full-stack developers — web dashboard, admin panel, device management
📝 Technical writers — documentation, tutorials, deployment guides

Every contribution matters — from fixing a typo to implementing a new provider. Open an issue, submit a PR, or just star the repo to show support.

GitHub Issues — Report bugs or request features Pull Requests — Submit your contributions

License

MIT License — see LICENSE for details.

Acknowledgements

V1Claw is heavily inspired by and based on PicoClaw by Sipeed. We are grateful to the PicoClaw team for building the foundation that made this project possible.

Name		Name	Last commit message	Last commit date
Latest commit History 316 Commits
.github		.github
assets		assets
cmd/v1claw		cmd/v1claw
config		config
docs		docs
pkg		pkg
workspace		workspace
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
Dockerfile		Dockerfile
Dockerfile.goreleaser		Dockerfile.goreleaser
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

License

amit-vikramaditya/V1Claw

Folders and files

Latest commit

History

Repository files navigation

V1Claw

Features

🧠 13 LLM Providers

🎤 Voice I/O Pipeline

📷 Vision & Camera

📱 10 Communication Channels

🛠️ 14 Built-in Tools

📱 Android/Termux Integration

🔒 Security

⏰ Proactive & Scheduled Tasks

🧩 Skills System

Setup Guide

📱 Android (Termux)

Step 1: Install two apps from F-Droid

Step 2: Grant permissions to Termux:API

Step 3: Install developer tools in Termux

Step 4: Download V1Claw

Step 5: Build V1Claw

Step 6: Run first-time setup

Step 7: Test it!

Step 8: Start chatting

Step 9: Enable phone hardware (optional)

Step 10: Run V1Claw 24/7 in the background (optional)

🍎 macOS

Step 1: Install Go (if you don't have it)

Step 2: Download V1Claw

Step 3: Build

Step 4: Run first-time setup

Step 5: Test it

Step 6: Interactive chat

Step 7: Run as a 24/7 service (optional)

🐧 Linux

Step 1: Install Go, Git, and Make

Step 2: Download V1Claw

Step 3: Build

Step 4: Run first-time setup

Step 5: Test it

Step 6: Run as a 24/7 system service (optional)

🪟 Windows

Step 1: Install Go and Git

Step 2: Download V1Claw

Step 3: Build

Step 4: Run first-time setup

Step 5: Test it

Step 6: Interactive chat

🐳 Docker (any platform)

🔗 Cross-Compile for Another Device

🌐 Multi-Device Setup (Tailscale)

Configuration Reference

Key Sections

Permissions

CLI Commands

Architecture

Roadmap — Towards a True 24/7 AI Assistant

✅ Done

🚧 In Progress

🔮 Future

Troubleshooting

Contributing

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages