Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dallay/corvus/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

Corvus can be installed in multiple ways depending on your platform and preferences. Choose the method that works best for your workflow.
Corvus ships as a single self-contained binary (3.4MB) with no external dependencies. All installation methods provide the same functionality.

​
Prerequisites

Before installing Corvus, ensure you have the following prerequisites for your chosen installation method:
Node.js 18+ (for package manager installation)Check your Node.js version:
node --version
If you need to install or update Node.js, visit nodejs.org.

​
Installation Methods

The fastest way to get started with Corvus is via npm, pnpm, yarn, or bun. The package automatically downloads and manages the appropriate Rust binary for your platform. 
# Global installation
npm install -g @dallay/corvus

# Or use npx without installing
npx @dallay/corvus --help
The npm package includes optional dependencies for each platform:
  • @dallay/corvus-darwin-x64 (macOS Intel)
  • @dallay/corvus-darwin-arm64 (macOS Apple Silicon)
  • @dallay/corvus-linux-x64 (Linux x64)
  • @dallay/corvus-linux-arm64 (Linux ARM64)
  • @dallay/corvus-windows-x64 (Windows x64)
Your package manager automatically installs only the binary for your platform.
Advantages:
  • No Rust toolchain required
  • Automatic platform detection
  • Easy updates via package manager
  • Works with npx/pnpm dlx/yarn dlx/bunx without installation
Disadvantages:
  • Requires Node.js 18+
  • Slightly larger download (includes npm wrapper)

​
Build from Source with Cargo

For maximum control and the latest development version, build Corvus from source using Cargo.
1

Clone the Repository

git clone https://github.com/dallay/corvus.git
cd corvus/clients/agent-runtime
2

Build Release Binary

cargo build --release
The binary will be available at:
  • Release: target/release/corvus
  • Debug: target/debug/corvus
  • Dist profile: target/dist/corvus
3

Install Globally (Optional)

Install the binary to your system:
cargo install --path . --force
This installs to ~/.cargo/bin/corvus (ensure this is in your PATH).
4

Verify Installation

corvus --version
Expected output:
corvus 0.2.2
Corvus uses multiple Cargo profiles for different use cases:
ProfileOptimizationLTOCodegen UnitsUse Case
release-Oz (size)thin1Standard distribution
release-fast-Ozthin8Fast builds on powerful machines (16GB+ RAM)
dist-Ozfat1Maximum size optimization for distribution
dev-O0none256Fast compilation during development
The default release profile uses codegen-units = 1 for low-memory devices like Raspberry Pi 3.
Advantages:
  • Latest development features
  • Maximum performance
  • Full control over build flags and features
  • No intermediate wrapper layers
Disadvantages:
  • Requires Rust toolchain (1.75+)
  • Longer build time (2-5 minutes on first build)
  • Must manually update via git pull

​
Binary Download

Download pre-built binaries directly from GitHub Releases.
1

Download for Your Platform

Visit the Corvus Releases page and download the appropriate binary:
  • macOS (Intel): corvus-darwin-x64
  • macOS (Apple Silicon): corvus-darwin-arm64
  • Linux (x64): corvus-linux-x64
  • Linux (ARM64): corvus-linux-arm64
  • Windows (x64): corvus-windows-x64.exe
2

Make Executable (macOS/Linux)

chmod +x corvus-*
3

Move to PATH (Optional)

sudo mv corvus-* /usr/local/bin/corvus
Or add the current directory to your PATH.
4

Verify Installation

corvus --version
Advantages:
  • No toolchain dependencies
  • Instant setup
  • Smallest download size (3.4MB)
Disadvantages:
  • Manual download and PATH setup
  • Manual updates required

​
Optional Dependencies

Corvus supports additional features via optional dependencies:

​
Docker (for Sandboxing)

To use Docker-based sandboxing for secure command execution: 
brew install docker
Enable in config:
~/.corvus/config.toml
[runtime]
kind = "docker"

[runtime.docker]
image = "alpine:3.20"
network = "none"
memory_limit_mb = 512
read_only_rootfs = true
mount_workspace = true

​
SurrealDB (for Advanced Memory)

To use SurrealDB as the memory backend: 
cargo build --release --features memory-surreal
Enable in config:
~/.corvus/config.toml
[memory]
backend = "surreal"

[memory.surreal]
url = "http://127.0.0.1:8000"
namespace = "corvus"
database = "memory"
allow_http_loopback = true
The SurrealDB feature requires building from source with --features memory-surreal. It’s not included in the npm distribution by default.

​
Platform-Specific Notes

​
macOS

Use the corvus-darwin-arm64 binary. If you see Rosetta 2 warnings, ensure you downloaded the ARM64 version, not x64.
file $(which corvus)
# Should show: Mach-O 64-bit executable arm64
On first run, macOS may block the binary with a security warning:
  1. Open System Preferences → Security & Privacy
  2. Click “Allow Anyway” next to the Corvus message
  3. Re-run the command
Or bypass Gatekeeper entirely:
xattr -d com.apple.quarantine /path/to/corvus

​
Linux

Ensure the binary is executable:
chmod +x corvus
Corvus is statically linked with musl for maximum compatibility. If you encounter GLIBC errors, ensure you’re using the correct binary for your architecture (x64 vs ARM64).
To run Corvus as a systemd service:
corvus service install --linger on
This creates a user service that survives logout and reboot.

​
Windows

Windows Defender may flag the binary as unrecognized. Add an exception:
  1. Open Windows Security → Virus & threat protection
  2. Click Manage settings → Add or remove exclusions
  3. Add the Corvus binary path
If scripts fail to run, update your execution policy:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

​
Verification

After installation, verify that Corvus is working correctly:
1

Check Version

corvus --version
Expected output:
corvus 0.2.2
2

Run Help Command

corvus --help
This displays all available commands and options.
3

Measure Binary Size and Startup Time

ls -lh $(which corvus)
/usr/bin/time -l corvus --help
Expected:
  • Binary size: ~3.4MB
  • Startup time: <10ms on modern hardware
4

Run System Diagnostics

corvus doctor
This checks for common issues and reports system health.

​
Updating Corvus

​
NPM Installation

npm update -g @dallay/corvus

​
Cargo Installation

cd corvus/clients/agent-runtime
git pull
cargo install --path . --force

​
Binary Download

  1. Download the latest release from GitHub Releases
  2. Replace your existing binary
  3. Restart any running Corvus services: 
    corvus service restart
Corvus checks for updates automatically when you run agent, daemon, or status commands. Set CORVUS_DISABLE_UPDATE_CHECK=1 to disable update notifications.

​
Next Steps

Quickstart

Complete the onboarding wizard and run your first agent

Configuration

Learn about all configuration options

Development

Set up your development environment

API Reference

Explore the complete API documentation

​
Troubleshooting

  1. Clear npm cache: npm cache clean --force
  2. Check Node.js version: node --version (requires 18+)
  3. Try with verbose logging: npm install -g @dallay/corvus --verbose
  4. Fall back to binary download or Cargo installation
Common causes:
  • Outdated Rust: Update with rustup update
  • Low memory: Use cargo build --profile release instead of --profile dist
  • Missing system dependencies: Install build-essential (Linux) or Xcode Command Line Tools (macOS)
For detailed error logs:
cargo build --release --verbose
macOS/Linux:
chmod +x corvus
Windows: Ensure you’re running PowerShell or Command Prompt as Administrator if moving to System32.
Ensure the installation directory is in your PATH:npm/pnpm/yarn/bun:
echo $PATH | grep -i npm
Cargo:
echo $PATH | grep -i cargo
Add to PATH if missing:
# Add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.cargo/bin:$PATH"
Still having issues? Check the GitHub Issues or join the community discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us