kosa8

kosa8 / Guides

Guide

How do I run an AI agent sandbox on my own machine instead of the cloud?

Updated 2026-10-31

Install a sandbox runtime that uses your computer's own hypervisor, start its background service, and create a sandbox for the agent to work in. With kosa8 that is one install line, kosa8 daemon start and kosa8 sandbox create: each sandbox is a microVM with its own kernel, running on an Apple silicon Mac or x86-64 Linux, so the agent's code, data and API keys never leave your hardware.

01Steps

  1. Check your machine can run sandboxes. Sandboxes are real virtual machines, so they need a hypervisor kosa8 can drive: Apple's Virtualization framework on an Apple silicon Mac, or KVM with Cloud Hypervisor on x86-64 Linux, which also needs cloud-hypervisor, virtiofsd and access to /dev/kvm. Windows 11 on x86-64 runs them in WSL2 as a preview. Intel Macs, Windows 10, Windows on ARM and JioOS get a remote client that connects to a machine that can.

  2. Install kosa8. Use the one-line installer on macOS or Linux. It works out your chip, checks the download against the published fingerprints and puts kosa8 on your PATH. Homebrew and a signed Mac app are alternatives; on Windows 11 run kosa8 wsl setup once after installing.

  3. Start the daemon and check it. Nothing runs until the background service is up. The first run fetches the guest image for your release, verifies its checksum and keeps it in ~/.kosa8/guest; kosa8 doctor reports anything missing.

  4. Create a sandbox and run something in it. Each sandbox has its own kernel, container engine and private image store, so nothing pulled inside it touches your host.

    terminal
    kosa8 sandbox create web --memory 2048
sandbox web ready in 640ms (32 GB disk)
kosa8 sandbox pull web alpine:3.20
kosa8 sandbox run web alpine:3.20 sh -c "hostname"
kosa8-guest
kosa8 sandbox ls

  5. Limit what it can see and reach. Decide up front which folder the agent sees and which hosts it can connect to. The limits are enforced on the host, so root inside the sandbox cannot lift them.

  6. Run a coding agent in its own sandbox. kosa8 agent run builds a sandbox from a kit, mounts one folder and starts the agent. Add --dry-run first to print the plan without starting anything.

02When does a local AI agent sandbox make sense?

Run the sandbox locally when the agent works on code or data that should stay on your hardware, when you need it to work offline or air-gapped, when you want no network round trip between the agent and its machine, when you want costs that do not grow per sandbox-hour, or when regulated work means you must be able to say exactly where the data was processed.

A local sandbox also keeps the agent next to your files: kosa8 can share a host folder into the sandbox read-only or read-write, and the privacy policy lists what the software sends anywhere. Your sandboxes, files, commands, snapshots and audit logs stay on your machine.

03When does a cloud sandbox fit better?

Use a cloud sandbox when you need to start many sandboxes at once, more than one computer can hold, when the agent serves users of a hosted product, or when the people or CI runners involved have no machine with a hypervisor to run sandboxes on.

A laptop has a fixed amount of memory and CPU, and every sandbox you run takes a share of it. Local folder sharing also has a cost: a folder shared from the host runs at about 29% of native speed in kosa8, so heavy I/O is faster on the sandbox's own disk. Many teams use both: local sandboxes for development and sensitive work, a hosted service for scale-out.

04Can a local AI agent sandbox run fully offline?

Yes. With KOSA8_OFFLINE=1 kosa8 fetches nothing, and you copy the guest image in from an air-gap bundle instead of downloading it. A sandbox created with --egress deny has no network at all, DNS included.

An offline sandbox is a natural pair for a local model: the agent, the model and the data all run on the same machine with nothing leaving it.

05Other options

Several tools run agent sandboxes, locally or as a service. Which fits depends on how strong the isolation needs to be, where the machines should run and how many you need.

  • microsandbox is a project on GitHub that runs microVM sandboxes on your own machine, self-hosted.
  • Lima runs Linux virtual machines on macOS with file sharing and port forwarding; UTM is a macOS app that runs full VMs using QEMU or Apple's Virtualization framework. A full VM gives strong isolation and complete control, with the setup and snapshots managed by you.
  • Docker containers are fast and familiar. On Linux they share the host kernel; Docker Desktop on a Mac runs them inside one Linux VM shared by all containers.
  • Claude Code's built-in /sandbox restricts the filesystem and network access of the commands Claude Code runs, using the operating system's own sandboxing, without a separate machine.
  • E2B, Daytona and Modal provide sandboxes as a hosted service you call from an SDK or API. They fit when you need many sandboxes on demand or have no local hardware to run them on.

06Sources