Skip to content

Latest commit

 

History

History
248 lines (170 loc) · 6.44 KB

_README.md

File metadata and controls

248 lines (170 loc) · 6.44 KB
monocore logo

monocore

Discord Build Status Monocore Crate Monocore Docs License

Building AI agents that write and execute code? You'll need a secure sandbox.

monocore provides instant, secure VMs for your AI agents to:

  • Generate visualizations and charts
  • Run data analysis scripts
  • Execute system commands safely
  • Create and host web applications
  • Run automated browser tasks
  • Perform complex calculations

All while keeping your system safe through VM-level isolation.

Warning

This project is in early development and is not yet ready for production use.

🤔 Why monocore?

When developing AI agents that execute code, you need a fast development cycle:

  • Docker containers? Limited isolation for untrusted code
  • Traditional VMs? Minutes to start up, heavy resource usage
  • Direct execution? Risky for your development machine
  • Cloud sandboxes? Great for production, but slow for rapid iteration

monocore gives you:

  • 🔒 True VM-level isolation
  • ⚡ Millisecond startup times
  • 🎯 Simple REST API
  • 📦 Works with standard container images
  • 🔧 Full resource control
  • 💻 Perfect for local development

Develop and test locally with instant feedback, then deploy to production with confidence.

🚀 Getting Started

Installation

curl -sSfL https://install.monocore.dev | sh

This will install both the monocore command and its alias mc.

System Requirements

Linux
  • KVM-enabled Linux kernel (check with ls /dev/kvm)
  • User must be in the kvm group (add with sudo usermod -aG kvm $USER)
macOS
  • Apple Silicon (ARM64) only
  • macOS 10.15 (Catalina) or later for Hypervisor.framework support
Windows

Local installation is not yet supported but you can use the SDK or REST API to interact with monocore remotely.

Quick Start

TODO: CLI: demo video of using the CLI.

SDK

TODO: Python SDK

REST API

TODO: Web UI and Curl examples

Troubleshooting

Service Won't Start

  • macOS: MicroVMs require at least 256 MiB of RAM to start properly. Setting lower values will cause silent failures. 
    [[service]]
name = "my-service"
ram = 256  # Minimum recommended for macOS

💻 Development

For development, you'll need to build monocore from source.

Prerequisites

Linux Requirements 
# Ubuntu/Debian:
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev flex bison bc libelf-dev python3-pyelftools patchelf

# Fedora:
sudo dnf install build-essential pkg-config libssl-dev flex bison bc libelf-dev python3-pyelftools patchelf
macOS Requirements

Make sure you have Homebrew installed, then:

brew tap slp/krun
brew install krunvm

Create a case-sensitive volume for krunvm:

diskutil apfs addVolume disk3 "Case-sensitive APFS" krunvm

Setup

  1. Clone the repository:

    git clone https://github.com/appcypher/monocore.git
cd monocore

  2. Install pre-commit hooks:

    pip install pre-commit
pre-commit install

Build and Install

  • Build the binaries and libraries:

    make build

  • Install the binaries and libraries:

    make install

  • Uninstall the binaries and libraries:

    make uninstall

Testing

Important

Run make install before running tests if you haven't already.

This ensures that the libkrun libraries are available to the tests even though they don't always need them.

  • Run unit tests:

    cargo test --lib

  • Run integration tests:

    cargo test --test '*'

  • Run all tests:

    cargo test

Release Process

When a release-please PR is created, the following manual changes need to be made before merging:

  1. Update Internal Dependencies: In the root Cargo.toml, ensure that any internal crate dependencies use the new release version being created. For example:

    [dependencies]
monoutils-x = { version = "0.2.0", path = "monoutils-x" }  # Update this version

  2. Update Install Script Version: In install_monocore.sh, update the version number to match the new release version.

These changes are not automatically handled by release-please and must be made manually before merging the release PR.

📚 Documentation

⚖️ License

This project is licensed under the Apache License 2.0.