https://github.com/arkavo-org/arkavo-edge
Secure, Sovereign, Self-Healing AI. A Rust-based agent runtime featuring OpenTDF protection and built-in observability.
https://github.com/arkavo-org/arkavo-edge
agent agentic-ai ai cli cross-platform encryption linux macos open-source opentdf rust windows
Last synced: 11 days ago
JSON representation
Secure, Sovereign, Self-Healing AI. A Rust-based agent runtime featuring OpenTDF protection and built-in observability.
- Host: GitHub
- URL: https://github.com/arkavo-org/arkavo-edge
- Owner: arkavo-org
- License: apache-2.0
- Created: 2025-05-17T18:37:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-01T02:55:37.000Z (about 2 months ago)
- Last Synced: 2026-05-01T03:18:13.910Z (about 2 months ago)
- Topics: agent, agentic-ai, ai, cli, cross-platform, encryption, linux, macos, open-source, opentdf, rust, windows
- Language: Rust
- Homepage:
- Size: 9.67 MB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 157
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Arkavo Edge
Instant, secure orchestration for AI agents—launch, mesh, and monitor in real time.
## Quick Start
### Install on macOS
Download the installer from the [releases page](https://github.com/arkavo-org/arkavo-edge/releases), open the .pkg file, and follow the installation wizard.
**For advanced users:** Install via Homebrew
```bash
brew tap arkavo-org/homebrew-arkavo
brew trust --formula arkavo-org/arkavo/arkavo # required on Homebrew 5.2+
brew install arkavo
```
### Install on Linux
```bash
brew tap arkavo-org/homebrew-arkavo
brew trust --formula arkavo-org/arkavo/arkavo # required on Homebrew 5.2+
brew install arkavo
```
**Raspberry Pi 5:** Download ARM64 binary from [releases](https://github.com/arkavo-org/arkavo-edge/releases). See [deployment guide](docs/raspberry-pi-deployment.md) for setup. First run auto-selects an edge model for the device (Pi 5 → Gemma 4 E4B).
### Install on Windows
Download the installer from the [releases page](https://github.com/arkavo-org/arkavo-edge/releases) and run the .exe file.
### Launch
```bash
# Start an agent (zero config)
arkavo
# Or launch web UI
arkavo ui
```
That's it. No configuration files, no setup. Agents auto-discover via mDNS and form a mesh.
On first run, Arkavo downloads two local models sized to your device — a small model for fast routing (Gemma 4 E2B) and a larger model for inference (Gemma 4 12B on desktop/workstation; Gemma 4 E4B on a Raspberry Pi 5).
### Trusting an agent
To authorize an agent (e.g. from another device), show its identity QR — the agent's `DID:key` and entitlements:
```bash
arkavo agent run --trust # or simply: arkavo --trust
```
## Coming from OpenClaw?
See the [migration guide](docs/openclaw-migration-guide.md) for a full comparison: what you gain (budget controls, TDF encryption, PII preflight, offline operation), what's different, and step-by-step setup.
## Why Arkavo?
- **Zero config:** Just run `arkavo`. Auto-naming, auto-routing, auto-discovery.
- **Fast:** Low-latency agent-to-agent communication (benchmarkable from source — see [Building from Source](#building-from-source)).
- **Visual:** See live agent communication flows in real-time.
## SwarmKit
Declarative multi-agent kits where each role declares its own TDF Attribute Release Policy. The orchestrator constructs role-scoped policies before any data reaches the role — push the trust boundary inward.
```bash
# Launch any kit at gateway boot
ARKAVO_SWARMKIT_PATH=examples/code-review-kit/code-review-kit.swarmkit.yaml arkavo
```
Four shipped kits: `campaign-kit`, `code-review-kit`, `vrm-production-kit`, `compliance-kit`. Full guide: [docs/SWARMKIT.md](docs/SWARMKIT.md). To validate a kit manifest from source, see [Building from Source](#building-from-source).
## Features
- **SwarmKit** - Declarative multi-agent kits with per-role TDF attribute-release policies. Four shipped examples covering marketing, code review, creative, and regulated domains. See [docs/SWARMKIT.md](docs/SWARMKIT.md).
- Multi-provider routing (OpenAI, Anthropic, Gemini, Kimi, DeepSeek, local models)
- **Local edge models via llama.cpp** - Gemma 4 (E2B/E4B/12B) by default; Ministral 3B/8B (with vision) also supported
- Cost-aware model selection (real per-token estimates on full macOS/Linux builds; the musl-slim and Windows binaries use an approximate estimator)
- iOS simulator automation (macOS only)
- Security scanning (Semgrep, OSV, SBOM)
## Usage Examples
### Chat
```bash
# Use any provider with API key
GEMINI_API_KEY=your-key arkavo chat --prompt "Hello"
DEEPSEEK_API_KEY=your-key arkavo chat --prompt "Explain Rust"
```
### Context Control Demo
The Autonomous Refactor demo demonstrates Active Context Management. It simulates a large-scale "breaking change" refactor that generates extensive compiler output, showing how the Context Ledger maintains a small active window while preserving data access.
```bash
cd examples/autonomous_refactor
./run_demo.sh
```
### Custom Agent Config (Optional)
```bash
arkavo agent init my-agent # Creates AGENTS.md template
# Edit AGENTS.md to set model, capabilities, API keys
arkavo # Runs with your config
```
### Security (Optional)
**OpenTDF Integration:** Fine-grained access control for MCP tools via [OpenTDF](https://opentdf.io). Set `OPENTDF_BASE_URL`, `OIDC_ISSUER`, and `AUD` environment variables.
## Coding Agent Toolset
The agent uses these MCP tools in-process during `chat` and `task` — there's no separate server to start. Tools that shell out to an external binary register only when that binary is on `PATH` (noted below).
### Code Search & Intelligence
- **codegrep_search**: Fast repository-wide code search with ripgrep
- **struct_find_replace**: Language-aware structural search and replace with Comby
- **syntax_tree**: AST parsing for syntax-aware code analysis with tree-sitter
### Security & Quality (require the named binary on `PATH`)
- **sec_semgrep**: SAST scanning with Semgrep
- **deps_osv**: Dependency vulnerability scanning with OSV-Scanner
- **sbom_syft**: SBOM generation with Syft
### Test & Automation
- **browser_cdp**: Chrome DevTools Protocol automation via chromiumoxide
- **test_run**: Multi-language test runner (pytest, jest, go test, cargo test, xcodebuild)
### Ephemeral Workspaces (requires Docker/Podman)
- **workspace_container**: Container-based isolated execution with resource quotas
These nine tools are the ones the running agent can call (the binary also registers git, GitHub, web-search, shell, and TDF tools — see the full reference below).
### Benchmark harness
SWE-bench evaluation lives in the separate `arkavo-mcp-bench` crate, run from source — it is **not** a registered agent tool (it depends on the orchestration engine, which would form a dependency cycle if exposed through the tool registry).
See [docs/coding-agent-toolset.md](docs/coding-agent-toolset.md) for complete tool documentation.
## Platform Support
| Platform | Architecture | Features |
|----------|-------------|----------|
| macOS | ARM64 (Apple Silicon) | Full support including iOS testing, local/remote LLM, mDNS |
| Linux | x86_64, ARM64 | Full support with local/remote LLM, mDNS |
| Linux (musl) | x86_64 | Static/slim binary with memory and mDNS support |
| Windows | x86_64 | Memory, remote LLM, and mDNS support (no iOS testing) |
mDNS discovery uses pure Rust implementation (mdns-sd crate) with no system dependencies
**Note:** iOS simulator automation and testing capabilities are only available on macOS.
## Building from Source
### Prerequisites
Install required build tools:
```bash
# macOS
brew install cmake ccache
# Linux (Debian/Ubuntu)
sudo apt install cmake ccache build-essential
# Linux (Fedora)
sudo dnf install cmake ccache gcc-c++
```
### Setup llama.cpp
Clone the llama.cpp dependency (not tracked in git):
```bash
git clone https://github.com/ggerganov/llama.cpp vendor/llama.cpp
cd vendor/llama.cpp
git checkout ef570f63087b6a5a2930210a13f87990e8113927
cd ../..
```
### Build
```bash
cargo build
```
The default build includes mDNS discovery using a pure Rust implementation (`mdns-sd` crate) that doesn't require system libraries like Avahi or Bonjour. This provides true portability across all platforms.
### Development
These commands run against the source tree (not the installed binary):
```bash
# Measure agent-to-agent latency
cargo bench -p arkavo-protocol --bench a2a_latency
# Validate a SwarmKit manifest
cargo run -p arkavo-swarmkit --example validate_kit -- \
examples/compliance-kit/compliance-kit.swarmkit.yaml
```