Skip to content

Commit 4e8374d

Browse files
PeronGHPeronGH
authored
docs(readme): rewrite around container runtime positioning (#351)
* docs(readme): rewrite around container runtime positioning * docs(readme): plainer prose, drop AI-writing tells * docs(readme): move quick start above containers * docs(readme): add AI agent and ArcBox Platform vision * docs(readme): fix wrapped ArcBox Platform name * docs(readme): lead platform section with bring-your-own-machine * docs(readme): trim Why ArcBox and de-dupe platform section
1 parent 65c5d7e commit 4e8374d

1 file changed

Lines changed: 139 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 139 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -2,143 +2,188 @@
22

33
# ArcBox
44

5-
**Sandboxed execution engine for AI agents, containers, and virtual machines.**
5+
**A fast, open-source container runtime for macOS.**
66

7-
**Built from scratch in Rust -- from hypervisor to CLI.**
7+
**Built from scratch in Rust. Drop-in Docker, native Kubernetes, and full Linux VMs.**
88

9-
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
10-
[![Rust](https://img.shields.io/badge/rust-1.85+-orange.svg)](https://www.rust-lang.org)
9+
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
10+
[![Rust](https://img.shields.io/badge/rust-1.96+-orange.svg)](https://www.rust-lang.org)
1111
[![Desktop](https://img.shields.io/github/v/release/arcboxlabs/arcbox-desktop?label=desktop&color=green)](https://github.com/arcboxlabs/arcbox-desktop/releases)
1212
[![Discord](https://img.shields.io/discord/1234567890?logo=discord&label=discord&color=5865F2)](https://arcbox.link/discord)
1313
[![Telegram](https://img.shields.io/badge/telegram-chat-26A5E4?logo=telegram)](https://arcbox.link/telegram)
1414
[![Docs](https://img.shields.io/badge/docs-arcbox.dev-blueviolet?logo=gitbook)](https://arcbox.link/docs)
1515

1616
</div>
1717

18-
---
19-
2018
## Why ArcBox
2119

22-
Computer Use is the next frontier for AI -- agents that can write files, run code, browse the web, and operate a real machine. But giving an agent a full computer means giving it a full attack surface. Containers share the host kernel; a single exploit and the agent is out.
20+
ArcBox is an open-source alternative to Docker Desktop and OrbStack on macOS.
21+
OrbStack set the bar for running Docker on a Mac quickly and with little overhead,
22+
but it is closed-source. ArcBox is open source under MIT/Apache-2.0, written from
23+
scratch in Rust, and aims to match it.
24+
25+
The same runtime gives each AI agent, CI job, or piece of untrusted code its own
26+
real microVM. The sandbox you run locally is the same primitive ArcBox Platform
27+
runs in the cloud, so you can build against local sandboxes and scale to a fleet
28+
without changing your code. ArcBox is in public beta. Join us on
29+
[Discord](https://arcbox.link/discord), or
30+
[open an issue](https://github.com/arcboxlabs/arcbox/issues).
2331

24-
ArcBox solves this with Firecracker-style microVMs that boot their own Linux kernel in under 200ms. Each sandbox is a real computer -- real filesystem, real network, real process tree -- with VM-level isolation that containers can't provide. And when you just need Docker, ArcBox is a drop-in replacement for Docker Desktop.
32+
## Quick start
33+
34+
```bash
35+
# Install with Homebrew
36+
brew install --cask arcboxlabs/tap/arcbox
2537

26-
## Three-Tier Runtime
38+
# or with the install script
39+
curl -fsSL https://get.arcbox.dev | bash
2740

28-
| Tier | Isolation | Boot Time | Overhead | Use Case |
29-
|------|-----------|-----------|----------|----------|
30-
| **Container** | Namespace + chroot | Instant | ~1 MB | Standard Docker workloads |
31-
| **Sandbox** | microVM (own kernel) | <200ms | ~10-30 MB | Untrusted code, CI/CD, AI agents |
32-
| **Machine** | Independent VM | ~1.5s | ~200 MB | Full Linux dev environment |
41+
# Start the daemon and enable Docker compatibility
42+
abctl daemon start
43+
abctl docker enable
3344

45+
# Run a container
46+
docker run -d -p 8080:80 nginx
47+
curl http://localhost:8080
3448
```
35-
Host
36-
├── arcbox daemon (Docker API + gRPC)
37-
│
38-
├── System VM (Container + Sandbox tiers, shared kernel)
39-
│ └── arcbox-agent
40-
│ ├── Container Runtime ── namespace + chroot
41-
│ └── Sandbox Runtime ─── KVM microVM (<200ms boot)
42-
│
43-
├── Machine VM "ubuntu-dev" (independent kernel + rootfs)
44-
└── Machine VM "alpine-test"
49+
50+
Run `abctl doctor` to check the runtime, and `abctl --help` to see every command.
51+
52+
## Containers
53+
54+
ArcBox is a drop-in Docker engine. It exposes a Docker-compatible socket and
55+
proxies to a guest `dockerd`, so the Docker CLI, your scripts, and your Compose
56+
files work without changes.
57+
58+
```bash
59+
abctl docker enable # creates and activates the "arcbox" Docker context
60+
docker run -d -p 8080:80 nginx
61+
docker compose up
62+
docker build -t myapp .
4563
```
4664

47-
### Sandbox — Computer Use Runtime
65+
Containers, images, Compose, port forwarding, bind mounts, named volumes, and
66+
interactive `exec` all work today.
4867

49-
Give an AI agent a real computer it can't break out of.
68+
### amd64 and arm64 images
5069

51-
- **<200ms cold boot** -- KVM microVM with minimal device model (virtio-MMIO only, no PCI/ACPI/BIOS)
52-
- **<50ms warm start** -- snapshot/restore for instant sandbox cloning
53-
- **VM-level isolation** -- each sandbox runs its own kernel; a vulnerability in one cannot escape to others
54-
- **Real computer** -- real filesystem, real networking, real process tree -- not a simulated shell
55-
- **Disposable** -- spin up, let the agent work, tear down; no state leaks between sessions
56-
- **Docker-compatible** -- `docker run --runtime=sandbox untrusted-image`
70+
ArcBox runs `linux/amd64` images on Apple Silicon next to native arm64. x86-64 is
71+
translated inside the guest by [FEX](https://github.com/FEX-Emu/FEX), an
72+
open-source emulator, with nothing to configure.
5773

58-
### Container
74+
```bash
75+
docker run --platform linux/amd64 alpine uname -m
76+
# x86_64
77+
```
5978

60-
Drop-in Docker engine replacement. Point your existing Docker CLI at ArcBox:
79+
### Native Kubernetes
80+
81+
A local k3s cluster, managed by the daemon, with host integration for `kubectl`.
6182

6283
```bash
63-
arcbox docker enable
64-
docker run -d -p 8080:80 nginx
84+
abctl k8s start
85+
abctl k8s kubeconfig >> ~/.kube/config
86+
kubectl get nodes
6587
```
6688

67-
### Machine
89+
### Migrate from Docker Desktop or OrbStack
6890

69-
Full Linux VMs with persistent storage, SSH access, and their own init system.
91+
Import your workloads from another local runtime.
7092

7193
```bash
72-
arcbox machine create dev --distro ubuntu
73-
arcbox machine ssh dev
94+
abctl migrate from docker-desktop
95+
abctl migrate from orbstack
7496
```
7597

76-
## Quick Start
98+
## Sandboxes
99+
100+
ArcBox can also run disposable microVMs, each with its own kernel, for AI agents,
101+
untrusted code, and CI jobs. You can snapshot a booted, idle sandbox and restore
102+
copies of it to skip a cold boot.
77103

78104
```bash
79-
# Install
80-
curl -sSL https://install.arcbox.dev | sh
105+
abctl sandbox create --memory 512
106+
abctl sandbox run <id> -- ./untrusted-binary
107+
abctl sandbox checkpoint <id> --name clean # capture a ready snapshot
108+
abctl sandbox restore clean # start a new sandbox from it
109+
```
81110

82-
# Start the daemon
83-
arcbox daemon start
111+
Create, run, exec, snapshot, and restore work today. We are aiming for cold boots
112+
under 200 ms, near-instant restore from a snapshot, and roughly 10–30 MB of
113+
overhead per sandbox.
84114

85-
# Enable Docker compatibility
86-
arcbox docker enable
115+
## Bring your own machine
87116

88-
# Run a container
89-
docker run -d -p 8080:80 nginx
90-
curl http://localhost:8080
117+
ArcBox Platform turns hardware you already own into cloud capacity. Enroll your
118+
Macs and Linux machines into a fleet, and they become on-demand compute for your
119+
team's sandboxes, builds, and CI, at the cost of your own hardware instead of
120+
premium cloud pricing. Apple Silicon is first-class, so the Mac capacity that the
121+
big clouds meter at a steep markup is simply yours to pool. (In development.)
122+
123+
## Machines
124+
125+
When you want a complete environment instead of a container, ArcBox can create
126+
full Linux VMs, each with its own kernel, persistent disk, and a distro you
127+
choose.
128+
129+
```bash
130+
abctl machine create dev --distro ubuntu
131+
abctl machine start dev
132+
abctl machine list
91133
```
92134

93-
## What Works Today
94-
95-
- **Container lifecycle** -- `run`, `stop`, `rm`, `logs`, `exec`, `inspect`
96-
- **Image management** -- pull from Docker Hub and OCI registries (ARM64)
97-
- **Port forwarding** -- `-p 8080:80` maps host ports into containers
98-
- **Volume mounts** -- bind mounts and named volumes
99-
- **Networking** -- internet access, DNS resolution, inter-container DNS
100-
- **Docker Compose** -- `docker-compose up/down` for multi-container stacks
101-
- **Context switching** -- `arcbox docker enable/disable` to toggle with Docker Desktop
102-
- **Machine management** -- `create/start/stop/rm/ls/inspect/exec/ssh`
103-
- **40+ Docker API endpoints** -- Docker Engine API v1.43 compatible
104-
105-
## Performance
106-
107-
Custom VirtIO stack, zero-copy networking, purpose-built VirtioFS.
108-
109-
| Metric | Container | Sandbox | Machine |
110-
|--------|-----------|---------|---------|
111-
| Boot | Instant | <200ms cold / <50ms warm | ~1.5s |
112-
| Memory | ~1 MB | ~10-30 MB | ~200 MB |
113-
| File I/O (vs native) | >90% | >85% | >90% |
114-
115-
| | ArcBox | E2B (Firecracker) | Docker Desktop |
116-
|--|--------|-------------------|----------------|
117-
| Sandbox boot | <200ms | ~150ms | N/A |
118-
| Container boot | Instant | N/A | Instant |
119-
| Idle memory | <150 MB | Cloud-only | 1-2 GB |
120-
121-
## Known Limitations
122-
123-
| Feature | Status |
124-
|---------|--------|
125-
| `docker build` | Not yet -- use `docker buildx` or pre-built images |
126-
| Sandbox runtime (`--runtime=sandbox`) | Designed, not yet implemented |
127-
| Machine distro management | Designed, not yet implemented |
128-
| x86/amd64 images (Rosetta) | Not yet -- ARM64 only |
129-
| Linux host | macOS first, Linux planned |
130-
| GUI | CLI only -- desktop app planned |
135+
Creating, starting, and managing Ubuntu and Alpine machines works today. Shell
136+
and SSH access into a running machine is coming.
137+
138+
## Built from scratch
139+
140+
Most of ArcBox's performance-critical code is custom rather than vendored:
141+
142+
- A VMM on Hypervisor.framework, with manual vCPU execution and a device model we
143+
maintain ourselves.
144+
- VirtIO devices: `virtio-net`, `virtio-blk`, `virtio-fs`, `virtio-console`,
145+
`virtio-vsock`, and a balloon device.
146+
- A macOS networking datapath in userspace: DHCP, DNS forwarding, TCP via
147+
`smoltcp`, and host socket proxying, with no `pf` NAT or `utun` device.
148+
- VirtioFS/FUSE filesystem sharing, and a vsock guest agent that speaks protobuf.
149+
- x86 translation through FEX, so `linux/amd64` images run on Apple Silicon.
150+
151+
These are the numbers we are working toward, with OrbStack for comparison:
152+
153+
| Metric | ArcBox | OrbStack |
154+
|--------|--------|----------|
155+
| Cold boot | <1.5 s | ~2 s |
156+
| Warm boot | <500 ms | <1 s |
157+
| Idle memory | <150 MB | ~200 MB |
158+
| File I/O (vs native) | >90% | 75–95% |
159+
| Network throughput | >50 Gbps | ~45 Gbps |
160+
161+
## Desktop app
162+
163+
ArcBox Desktop is a native SwiftUI app. It talks to the daemon over gRPC and uses
164+
the Docker-compatible API for Docker resources. It covers Docker (containers,
165+
images, volumes, networks) and Kubernetes (pods, services), and includes log
166+
streaming, a terminal, and a file browser for a container's filesystem. Source:
167+
[arcboxlabs/arcbox-desktop](https://github.com/arcboxlabs/arcbox-desktop).
168+
169+
## What's next
170+
171+
- Shell and SSH access for machines
172+
- Faster x86 translation
173+
- Linux host support (macOS first)
174+
- Wider Docker Engine API coverage
131175

132176
## Requirements
133177

134-
- macOS 13 (Ventura) or later
135-
- Apple Silicon (M1/M2/M3/M4) -- Intel support in progress
136-
- Docker CLI installed (ArcBox replaces the engine, not the CLI)
178+
- macOS on Apple Silicon. Intel support is in progress.
179+
- The Docker CLI. ArcBox replaces the engine, not the CLI; `abctl docker setup`
180+
can install it for you.
137181

138182
## Contributing
139183

140-
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, code standards,
141-
and development setup.
184+
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, code standards, and
185+
development setup. The runtime is open source under MIT/Apache-2.0. Personal use
186+
is free, and commercial use is free during the public beta.
142187

143188
## License
144189

@@ -148,6 +193,6 @@ and development setup.
148193

149194
<div align="center">
150195

151-
**[Website](https://arcbox.dev)** · **[Docs](https://arcbox.link/docs)** · **[Discord](https://arcbox.link/discord)**
196+
[Website](https://arcbox.dev) · [Docs](https://arcbox.link/docs) · [Discord](https://arcbox.link/discord)
152197

153198
</div>

0 commit comments

Comments
 (0)