# Localbox

> Localbox gives Claude Code, Codex and other agents a durable Linux VM on an Apple Silicon Mac. The CLI is the primary interface; MCP is optional. The host daemon, VM and remote relay share one operation catalog.

Requirements: Apple Silicon, macOS 13 or newer, agent-installed. Linux hosts can use the protocol fixtures but cannot run the native macOS HostDaemon.

## Install

If the user asks you to install Localbox, follow this request:

    Install Localbox for me by following https://localbox.dev/llms.txt

Use the [agent installation procedure](https://raw.githubusercontent.com/dzhng/agent-computer/main/skills/localbox/references/installation.md). Resolve one stable GitHub release tag, download the complete app and CLI kit plus `release.json` and `SHA256SUMS`, verify them with the pinned Ed25519 public key, and invoke the release installer. The agent installs the product; there is no browser app download step.

The installed release carries its own ARM64 Node runtime and pinned `skills@1.7.0` installer. It installs the global Localbox skill without host `npx`, `npm`, or a package fetch, then registers HostDaemon and the six-hour updater with launchd. Verify with `localbox status`, `localbox skill status --json`, and `localbox help --json`.

## Use

- `localbox vm start`, `localbox vm stop`, and `localbox status` manage the local computer.
- `localbox shell exec -- <command>` runs bounded commands in the guest.
- `localbox login` authenticates remote relay use; it is independent of MCP.
- `localbox mcp install --json` prints optional MCP configuration.
- [Localbox skill](https://raw.githubusercontent.com/dzhng/agent-computer/main/skills/localbox/SKILL.md) is the agent-facing workflow and recovery guide.

## What it provides

- Install the tools I need and run the project tests.
- Open the browser in the VM and check the staging site.
- Run this command in an isolated Linux environment and show me the output.
- Take a screenshot of the desktop after the build finishes.
- Keep the VM state between sessions and reconnect after sleep.
- Use MCP for this task, but keep the CLI as the source of truth.

## Principles

- CLI and MCP expose the same catalog, schemas and behavior.
- The VM is the execution boundary; the host daemon owns lifecycle and the persistent disk.
- Remote relay traffic is authenticated, bounded and outbound from the host.
- Releases and managed skill updates verify signatures and checksums before replacement.
- Existing unmanaged skills and project-local skills are left alone.

## Links

- [Repository](https://github.com/dzhng/agent-computer)
- [Latest release](https://github.com/dzhng/agent-computer/releases/latest)
- [Installation reference](https://raw.githubusercontent.com/dzhng/agent-computer/main/skills/localbox/references/installation.md)
- [Optional MCP reference](https://github.com/dzhng/agent-computer#product-direction)