Frequently Asked Questions

Caro is a privacy-first AI shell assistant that converts natural language into safe, validated shell commands. It runs 100% locally on your machine—your commands, file paths, and data never leave your computer.

The easiest way is via cargo: cargo install caro. You can also use our install script: bash <(curl --proto '=https' --tlsv1.2 -sSfL https://setup.caro.sh). For other options, see our installation guide.

Caro runs on macOS, Linux, and Windows (WSL). You need Rust 1.70+ for building from source. For local LLM inference, we recommend 8GB+ RAM. Apple Silicon Macs get hardware acceleration with MLX.

It depends on your backend choice. Local backends (Ollama, MLX, llama.cpp) require no API keys. Cloud backends (Anthropic, OpenAI) require API keys. Caro defaults to trying local inference first.

Caro uses pattern-based command validation, not AI-based filtering. Every generated command is checked against known dangerous patterns (rm -rf /, fork bombs, disk wipers) before you run it. This is deterministic, not probabilistic—the same command always gets the same safety assessment.

Caro shows a clear warning explaining why the command is dangerous and what it would do. You can still proceed if you intend to run it—Caro is a seatbelt, not a straitjacket. For truly destructive commands, you'll need to explicitly confirm.

No. Caro runs 100% locally by default. Your commands, file paths, server names, and directory structures never leave your machine. If you choose to use a cloud backend (like Anthropic or OpenAI), only the natural language prompt is sent—not your command history or file system data.

Yes—Caro is designed with AI agents in mind. We recommend defense in depth: run agents as unprivileged users, sandbox to specific directories, use container isolation, and let Caro validate commands. Each layer catches what others miss.

Safety patterns are baked into the binary. When you update Caro (cargo install caro --force), you get the latest patterns. The core dangerous commands don't change. We also accept pattern contributions via GitHub.

Caro supports multiple backends: Local: Ollama, MLX (Apple Silicon), llama.cpp. Cloud: Anthropic Claude, OpenAI GPT. Caro automatically selects the best available backend or you can specify one explicitly.

For privacy and offline use, choose local backends. On Apple Silicon Macs, MLX offers the best performance with hardware acceleration. Ollama is great cross-platform. For best quality responses, cloud backends like Claude typically perform better but require API keys.

Install Ollama from ollama.ai, then run ollama pull llama3 (or another model). Caro will automatically detect Ollama when it's running. You can verify with caro --backend ollama "list files".

MLX is built into Caro for Apple Silicon Macs. Ensure you have the mlx Python package installed. Caro will automatically use MLX when available on M1/M2/M3 Macs for hardware-accelerated local inference.

Yes! With Ollama, you can use any GGUF model. With MLX, you can use any MLX-compatible model. Point Caro to your model with the --model flag or set it in your config file.

Simply run caro "your request in natural language". For example: caro "find all Python files modified in the last week". Caro generates the command, shows it to you with a safety assessment, and asks for confirmation before running.

By default, Caro shows you the command and waits for confirmation. You can use --execute or -e to auto-execute safe commands, but dangerous commands always require explicit confirmation.

Caro detects your shell ($SHELL) at runtime and generates appropriate syntax. It works with bash, zsh, fish, and POSIX sh. On macOS, it knows you're using BSD tools; on Linux, it adjusts for GNU syntax.

Yes! Use caro --quiet for scripting. You can pipe output, use in CI/CD, or integrate with other tools. The --output json flag outputs structured data for programmatic use.

Caro uses a config file at ~/.config/caro/config.toml. You can set your preferred backend, default model, safety level, and other options. Run caro --help to see all configuration options.

This means Caro couldn't find a local LLM or API key. Either: (1) Install and start Ollama with a model, (2) Set up MLX if on Apple Silicon, or (3) Set an API key for a cloud provider with export ANTHROPIC_API_KEY=....

Local inference speed depends on your hardware and model size. Try a smaller model (7B instead of 70B), use MLX on Apple Silicon for acceleration, or switch to a cloud backend for faster responses.

You can: (1) Rephrase your request to be more specific, (2) Add context like "on macOS" or "using find command", (3) Try a different backend/model, or (4) Report the issue on GitHub so we can improve.

Open an issue on our GitHub repository at github.com/wildcard/caro/issues. Include your OS, Caro version (caro --version), backend, and steps to reproduce.

By default, Caro collects minimal, anonymous usage metrics to help us improve the product—things like command success rates and which backends are used. No commands, file paths, or personal data are ever collected. See our telemetry page for details.

Yes. Set telemetry = false in your config file or use export CARO_TELEMETRY=false. Caro will work exactly the same with telemetry disabled.

Yes. We don't collect personal data. All telemetry is anonymous and aggregated. You have full control over what data is sent (if any), and can disable telemetry entirely.

We welcome contributions! You can: submit bug reports, propose features, contribute code (it's Rust!), add safety patterns, improve documentation, or help with translations. See our contributing guide.

Yes! Caro is licensed under AGPL-3.0. You can read, modify, and distribute the source code. The full codebase is available on GitHub.

You can support us through GitHub Sponsors or Open Collective. Every contribution helps us maintain and improve Caro. See our support page for more details.