Evaggelos Balaskas - System Engineer

The sky above the port was the color of television, tuned to a dead channel

Blog
Posts
Wiki
About
Contact
rss.png twitter linkedin github gitlab profile for ebal on Stack Exchange

Next Page »
  -  
Oct
30
2026
Running AI Agents inside a microVM sandbox
Posted by ebal at 17:25:55 in blog

I wanted to run an AI coding agent harness in an isolated environment. You can find several programs such as Docker containers, Kata Containers, Firecracker, smolvm, krunvm, brig.sh, and Microsandbox. There are pros and cons to all of them. I wanted something I could run locally without much effort and with a simple setup.

For my ArchLinux system with KVM enabled, I chose Microsandbox, a local runtime for microVM which each sandbox runs as a lightweight virtual machine with its own Linux kernel, filesystem, and network boundary.

Check KVM support

First thing, is that we much verify we already have a KVM device (virtualization enabled) and our user is indeed on the kvm group!

ls -l /dev/kvm             # usually: crw-rw---- root kvm
id $USER                   # is "kvm" in the groups?

sudo usermod -aG kvm $USER # only if it's missing
id $USER                   # is "kvm" in the groups?

Install the Linux binary files

I wanted to avoid the curl | sh approach, so I downloaded version v0.7.11 and its libkrunfw library into my home directory.

The installation uses one binary and one library from libkrunfw, 2 files total!

To make it simple to copy/paste to your system:

mkdir -p ~/.microsandbox/{bin,lib}

V=v0.7.11
B="https://github.com/superradcompany/microsandbox/releases/download/$V"

curl -sfL -o ~/.microsandbox/bin/msb "$B/msb-linux-x86_64"
chmod 755 ~/.microsandbox/bin/msb
curl -sfL -o ~/.microsandbox/lib/libkrunfw.so.5.6.1 "$B/libkrunfw-linux-x86_64.so"

export PATH="$HOME/.microsandbox/bin:$PATH"

I ran the self-update command to check the installation. It reported that version v0.7.11 was current and linked msb and microsandbox in ~/.local/bin:

$ msb self update
 • Current version: v0.7.11
 • Latest version: v0.7.11
 ✓ Already up to date.
 ✓ Linked              /home/ebal/.local/bin/msb -> /home/ebal/.microsandbox/bin/msb
 ✓ Linked              /home/ebal/.local/bin/microsandbox -> /home/ebal/.microsandbox/bin/microsandbox

Check the host

I ran msb doctor to check the host. It found the required binary and library, CPU virtualization support, and the KVM device. It also reported that APICv was disabled by KVM policy:

$ msb doctor
 • Platform            Linux x86_64
 • Version             v0.7.11
 • MSB_HOME            /home/ebal/.microsandbox
 ✓ msb                 /home/ebal/.microsandbox/bin/msb
 ✓ libkrunfw           /home/ebal/.microsandbox/bin/../lib/libkrunfw.so.5.6.1
 ✓ Root clone          reflink supported
 ✓ CPU virt            vmx
 ✓ KVM device          /dev/kvm
 ✓ KVM access          read/write
warn: KVM APICv: disabled by KVM policy
warn: Intel APICv is disabled by KVM policy
 → APICv is optional; sandbox correctness and isolation are unaffected
 → it is a privileged, host-wide KVM setting; stop all KVM guests first
 → enable for the current boot: sudo modprobe -r kvm_intel && sudo modprobe kvm_intel enable_apicv=1
 → verify: cat /sys/module/kvm_intel/parameters/enable_apicv
 ✓ Host setup is ready.

APICv is optional. The doctor output says that disabling it does not affect sandbox correctness or isolation. Changing this setting affects the host and requires stopping all KVM guests first, so I left it unchanged.

MacOS

You can also install microsandbox to your macbook, and for this I will show the curl | bash approach:

❯ curl -fsSL https://install.microsandbox.dev | sh

  Microsandbox Installer

info Detected platform: darwin-aarch64
info Latest version: v0.7.11
info Downloading microsandbox...
[#---------------------------------------]   3%  1MB/30MB  microsandbox-darwin-aarch64.tar.gz^R
[########################################] 100%  30MB/30MB  microsandbox-darwin-aarch64.tar.gz
[########################################] 100%  0MB/0MB  checksums.sha256
info Verifying checksum...
done Checksum verified
info Extracting...
done Installed msb to /Users/<user>/.microsandbox/bin/msb
done Linked microsandbox -> msb in /Users/<user>/.microsandbox/bin/
done Installed libkrunfw to /Users/<user>/.microsandbox/lib/
done Linked /Users/<user>/.local/bin/msb -> /Users/<user>/.microsandbox/bin/msb
done Linked /Users/<user>/.local/bin/microsandbox -> /Users/<user>/.microsandbox/bin/microsandbox

  Note: /Users/<user>/.local/bin is not on your PATH.
  Add it to your shell profile if you want to run msb directly:

    export PATH="/Users/<user>/.local/bin:$PATH"

done Installation complete! Run '/Users/<user>/.local/bin/msb --help' to get started.

Start Ubuntu

Microsandbox can run OCI images, so it can use docker container images. I started an Ubuntu image with msb run ubuntu:

$ msb run ubuntu

root@msb-3cd3976f:/# grep VERSION /etc/os-release
VERSION_ID="26.04"
VERSION="26.04.1 LTS (Resolute Raccoon)"
VERSION_CODENAME=resolute

root@msb-3cd3976f:/# uname -a
Linux msb-3cd3976f 6.12.113 #1 SMP Fri Jul 24 13:01:52 WAT 2026 x86_64 GNU/Linux

root@msb-3cd3976f:/# exit
exit

The image was available locally after the run:

$ msb image ls
REFERENCE    DIGEST                 SIZE        CREATED
ubuntu       sha256:157dc3d6e4a3    40.2 MiB    2026-10-30 15:04:28

Microsandbox running Ubuntu

and on your macbook:

❯ msb run ubuntu

root@msb-7d63a2f7:/# uname -a
Linux msb-7d63a2f7 6.12.113 #1 SMP Fri Jul 24 13:01:52 WAT 2026 aarch64 GNU/Linux

root@msb-7d63a2f7:/# grep -i ^version /etc/os-release
VERSION_ID="26.04"
VERSION="26.04.1 LTS (Resolute Raccoon)"
VERSION_CODENAME=resolute

Running the OpenCode agent harness

Now the interesting part, can I run a micro isolated virtual machine to run my AI coding agent with access only to my program ?

So, I pulled the latest OpenCode image:

$ msb pull ghcr.io/anomalyco/opencode
 ✓ Pulled              ghcr.io/anomalyco/opencode (13.8s)

and I checked that the image was available locally:

$ msb image ls
REFERENCE                     DIGEST                 SIZE        CREATED
ghcr.io/anomalyco/opencode    sha256:c19f5dd52946    86.6 MiB    2026-10-30 15:21:21

Then I created a small project directory and a Python file for the agent to work with:

mkdir -pv ~/project_a/
echo 'print("Hello World!")' > ~/project_a/HelloWorld.py

I started the OpenCode image with the project directory mounted at /workspace. The sandbox has 2 GB of memory as opencode needs at least 2G of RAM to work:

msb run -t --name opencode --replace
  --mount-dir ~/project_a/:/workspace:rw
  --workdir /workspace --memory 2G
  ghcr.io/anomalyco/opencode

it worked as you can see below

OpenCode running in Microsandbox

OpenCode working with the Python file

That’s it !
Evaggelos

Tag(s): kvm, microvm, microsandbox, AI, agent
    Tag: kvm, microvm, microsandbox, AI, agent
Jul
06
2026
AI Coding Agents with One Shared Memory
Posted by ebal at 16:36:36 in blog

coding agents are useful, but they forget. I’ve find it from time and time to either repeat my self or creating skills to reuse them. But I also use multiple agents and on different machines too which is also complicated. I was looking for a way to keep a common memory to my agents. And built my services and setup without … forgetting !

This guide shows a simple MVP setup for giving your AI coding agents one shared memory system.

coding agents talk to MCP


What we are building

I will be using Basic Memory as the memory service and connect agents through MCP, running it with docker compose using the official image.

Model Context Protocol (MCP) is an open standard introduced by Anthropic in November 2024 that enables AI agents and large language models (LLMs) to securely connect with external tools, data sources, and services

One agent writes a note, any agent — in any later session — can retrieve it back. You can also open the same files yourself, since they are just Markdown files on disk.So basic memory becomes a shared notebook for your coding agents.


What you need

You need:

  • Docker
  • Docker Compose
  • Git (optional)
  • A terminal
  • One coding agent with MCP support

No model provider API key needed here. Basic Memory’s default semantic search runs on local FastEmbed embeddings.

Official docs:

  • Basic Memory repo: https://github.com/basicmachines-co/basic-memory
  • Basic Memory docs: https://docs.basicmemory.com/
  • Basic Memory Docker guide: https://github.com/basicmachines-co/basic-memory/blob/main/docs/Docker.md

Why no model provider is needed

Some memory systems have an LLM read your conversation and extract facts before storing anything - every save costs a model call, and you need a provider API key for that.

Basic Memory skips this. The agent (or you) writes structured Markdown directly:

---
title: Testing Conventions
permalink: testing-conventions
tags: [testing]
---

# Testing Conventions

## Observations
- [tool] Use Vitest instead of Jest
- [rule] Do not edit generated files

## Relations
- relates_to [[Project Architecture]]

Observations, Relations, done. A local SQLite index gives full-text and semantic search over these files, no cloud calls.


Step 1: Start Basic Memory with Docker Compose

Default install is uv tool install basic-memory (or uvx basic-memory mcp), a stdio MCP server per agent - no Docker needed. I wanted one server for all my agents, so Docker it is.

The pre-built image runs as UID/GID 1000, so create and own the folders first:

mkdir -p knowledge basic-memory-config
sudo chown -R 1000:1000 knowledge basic-memory-config

docker compose

docker-compose.yml

name: basic-memory

# runs the MCP server over SSE/HTTP on :8000 - no auth on that endpoint.
# keep it on a trusted network, or put a reverse proxy + auth in front of it.

services:
  basic-memory:
    image: ghcr.io/basicmachines-co/basic-memory:latest
    container_name: basic-memory-server

    volumes:
      - ./knowledge:/app/data:rw
      # config + sqlite index, container user is appuser -> /home/appuser
      - ./basic-memory-config:/home/appuser/.basic-memory:rw

    environment:
      - BASIC_MEMORY_DEFAULT_PROJECT=main
      - BASIC_MEMORY_SYNC_CHANGES=true
      - BASIC_MEMORY_LOG_LEVEL=INFO
      - BASIC_MEMORY_SYNC_DELAY=1000

    ports:
      - "8000:8000"

    command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]

    restart: unless-stopped

    healthcheck:
      test: ["CMD", "basic-memory", "--version"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

and start it:

docker compose -v up -d

Confirm it’s healthy:

docker compose -v ps -a

# view logs
docker compose logs -f basic-memory

a healthy container looks like this in the logs:

❯ docker compose logs -f basic-memory
basic-memory-server  | [07/06/26 09:23:04] INFO     Starting MCP server 'Basic Memory'
basic-memory-server  |                              with transport 'sse' on
basic-memory-server  |                              http://0.0.0.0:8000/mcp
basic-memory-server  | INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Step 2: Confirm the project

The default project (main) is your ./knowledge folder, mounted into the container at /app/data. To add another project pointing at a different mounted folder:

docker exec basic-memory-server basic-memory project add my-project /app/data/my-project
docker exec basic-memory-server basic-memory project list

Decide upfront whether you want one shared notebook across all your repos, or one project per repo — it’s easier to choose now than to migrate later.

If you just want to have one shared notebook, then ignore project add my-project command.


Step 3: Connect Claude Code

Claude Code connects over SSE, worked fine against the Dockerized server:

claude mcp add --transport sse basic-memory http://localhost:8000/mcp

Verify inside Claude Code:

/mcp

Expect something like:

Local MCPs (/home/<user>/.claude.json [project: <project path>])
❯ basic-memory · ✔ connected · 23 tools

To remove it:

claude mcp remove basic-memory

There’s also a Claude Code plugin for session-start briefings and /basic-memory:* commands, optional:

claude plugin marketplace add basicmachines-co/basic-memory --sparse .claude-plugin plugins/claude-code
claude plugin install basic-memory@basicmachines-co

OpenCode example

OpenCode has a native "remote" MCP type, also worked directly against the same server, no proxy. Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "basic-memory": {
      "type": "remote",
      "url": "http://localhost:8000/mcp",
      "enabled": true
    }
  }
}

Verify:

opencode mcp list

Expect:

┌  MCP Servers
│
●  ✓ basic-memory connected
│      http://localhost:8000/mcp
│
└  1 server(s)

OpenCode’s config shape for remote MCP servers might change, check their docs if it stops working: https://opencode.ai/docs/mcp-servers/


Test it

Ask your connected agent, in plain language:

"Create a note about our project architecture decisions."

A Markdown file should appear under ./knowledge on your host in real time. Open it — you’ll see the frontmatter, an Observations list, and a Relations list. That’s the entire format.

Then start a fresh session (or switch agents) and ask:

Retrieve all notes from basic-memory

If the agent surfaces what you saved earlier, memory is working end to end. In practice it looks like this:


What to put in memory

Good:

  • Project conventions
  • Folder structure
  • Testing framework
  • Architecture decisions
  • Things the agent should avoid

here is an example from my homepc:

❯ tree knowledge/
knowledge/
└── basic-memory
    ├── conventions
    │   └── Docker Healthcheck Convention.md
    ├── projects
    │   ├── Changelog Conventions.md
    │   ├── Deployment Preferences.md
    │   ├── Git Commit Conventions.md
    │   └── README Conventions.md
    └── services
        ├── Hermes Agent.md
        ├── Port Registry.md
        ├── Port Suggestion Registry.md
        └── Service Registry.md

5 directories, 9 files

Bad:

do not put

  • Passwords
  • Private keys
  • Production tokens
  • Customer private data

See the Security notes near the top — treat ./knowledge like any other sensitive project directory, and don’t commit it to a public repo unless that’s actually intended.


Troubleshooting

Agent can’t connect to the MCP server? run the proxy bridge manually and see what breaks:

uvx mcp-proxy http://localhost:8000/mcp

Your coding agent cannot connect to an MCP server that isn’t reachable, obviously.

Notes not showing up, or search feels stale:

docker exec basic-memory-server basic-memory status
docker exec basic-memory-server basic-memory doctor

doctor checks file-vs-database consistency and rebuilds the local search index if it’s out of sync.

Running multiple projects and not sure which one is active:

docker exec basic-memory-server basic-memory project list

I hope you find the article useful.

That’s it !
-Evaggelos

Tag(s): basic-memory, agent, ai, opencode, claude
    Tag: basic-memory, agent, ai, opencode, claude
  -  

Search

Admin area

  • Login

Categories

  • blog
  • wiki
  • pirsynd
  • midori
  • books
  • archlinux
  • movies
  • xfce
  • code
  • beer
  • planet_ellak
  • planet_Sysadmin
  • microblogging
  • UH572
  • KoboGlo
  • planet_fsfe

Archives

  • 2026
    • November
    • October
    • August
    • July
    • June
    • May
    • April
    • March
    • January
  • 2025
    • December
    • October
    • September
    • April
    • March
    • February
  • 2024
    • November
    • October
    • August
    • April
    • March
  • 2023
    • May
    • April
  • 2022
    • November
    • October
    • August
    • February
  • 2021
    • November
    • July
    • June
    • May
    • April
    • March
    • February
  • 2020
    • December
    • November
    • September
    • August
    • June
    • May
    • April
    • March
    • January
  • 2019
    • December
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2018
    • December
    • November
    • October
    • September
    • August
    • June
    • May
    • April
    • March
    • February
    • January
  • 2017
    • December
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2016
    • December
    • November
    • October
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2015
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • January
  • 2014
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2013
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2012
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2011
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2010
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
  • 2009
    • December
    • November
    • October
    • September
    • August
    • July
    • June
    • May
    • April
    • March
    • February
    • January
Ευάγγελος.Μπαλάσκας.gr

License GNU FDL 1.3 - CC BY-SA 3.0