monocore

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 test 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

Coming soon!

Quick Start

1. Define your sandboxes

   # monocore.toml
   [[service]]
    name = "sh-counter"
    base = "alpine:latest"
    ram = 256
    cpus = 1
    group = "demo"
    command = "/bin/sh"
    args = ["-c", "for i in $(seq 1 20); do echo $i; sleep 2; done"]
   
    [[service]]
    name = "python-counter"
    base = "python:3.11-slim"
    ram = 256
    cpus = 1
    group = "demo"
    command = "/usr/local/bin/python3"
    args = [
        "-c",
        "import time; count=0; [print(f'Count: {count+1}') or time.sleep(2) or (count:=count+1) for _ in range(20)]",
    ]
   
    [[group]]
    name = "demo"
    local_only = true

2. Manage your sandboxes

   Start sandboxes:

   mc up -f monocore.toml

   Check status:

   mc status

   Check logs:

   mc log sh-counter --no-pager -n 10

   Stop specific services:

   mc down --group demo

   Stop all services:

   mc down

   Remove services:

   mc remove timer counter

   For a complete list of commands and options, use:

   mc --help

REST API

Start the server (default port: 3456):

mc serve

Launch sandboxes:

curl -X POST http://localhost:3456/up \
  -H "Content-Type: application/json" \
  -d @monocore.example.json

Check status and metrics:

curl http://localhost:3456/status | jq

Stop all services:

curl -X POST http://localhost:3456/down

Stop specific group:

curl -X POST http://localhost:3456/down \
  -H "Content-Type: application/json" \
  -d '{"group": "app"}'

Remove services:

curl -X POST http://localhost:3456/remove \
  -H "Content-Type: application/json" \
  -d '{"services": ["timer"]}'

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

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

make build
make install

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

• Detailed Features
• Architecture
• API Examples
• Development Guide

⚖️ License

This project is licensed under the Apache License 2.0.