◈ loopbox

Local sandbox control plane for macOS.

One IP per project. Stable hostnames. Agent-ready debugging.

---

Each project gets a dedicated loopback IP and stable .localhost hostnames, routed through an internal reverse proxy and managed from a native desktop GUI. Host-based HTTP routes and loopback endpoint listeners for gRPC/TCP are configured from the same sandbox model. Keep URLs consistent across projects, isolate browser storage per hostname, start services, tail logs, inspect traffic, merge .env files, and let local AI agents control runtime + debugging workflows via the Agent API. Docker can coexist: bind containers to a sandbox IP to reuse common ports without cross-project conflicts.

frontend.myapp.localhost  →  127.0.0.2:5173
backend.myapp.localhost   →  127.0.0.2:8080
gateway.myapp.localhost   →  127.0.0.2:3000
127.0.0.1:50051           →  127.0.0.2:50051  (grpc_h2c)
127.0.0.1:15432           →  127.0.0.2:15432  (tcp_passthrough)

Features

• Sandbox Identity — stable loopback IP + generated hostnames per project for predictable URLs, isolated browser storage, and managed /etc/hosts entries
• Reverse Proxy Layers — host-based HTTP routing (service.project.localhost) plus loopback endpoint listeners (grpc_h2c, tcp_passthrough); falls back to :18080 with pf redirect if :80 is unavailable
• Paid Docker Management (Pro/Ultimate) — paid builds can bind containers to a sandbox IP (for example 127.0.0.30) so multiple projects can reuse the same container ports without collisions
• Multi-Port Services — each service can define multiple port + protocol + health entries (http1, grpc_h2c, tcp_passthrough)
• Process Runtime — start/stop/restart individually or all at once; PID registry survives app restarts
• Live Logs — combined stdout/stderr per service, tailed in-app
• HTTP + gRPC Traffic Inspector — available only in private edition builds
• gRPC Proto Decode — optional project proto paths for typed payload decoding via protoc with --decode_raw fallback (private editions)
• Command Discovery — scans package.json recursively; scores suggestions by service name; detects package manager from lockfiles
• Env Management — discovers and merges .env* files; injects LOOPBOX_* vars (LOOPBOX_PORT_*, LOOPBOX_PORTS_*, LOOPBOX_URL_*) into every spawned process and terminal
• Vite Intelligence — auto-injects --host, --port, --strictPort, and __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS
• Terminal Integration — one click opens macOS Terminal with working directory and merged env
• Health Checks — TCP port reachability + optional HTTP path and gRPC health target checks; running vs unhealthy state distinction
• Doctor — validates IPs, /etc/hosts, loopback aliases, DNS, ports, and env files; includes direct fix actions
• Local Agent API — localhost HTTP API for tools like Codex/Claude/Cursor (projects, runtime, logs, requests, start/stop/restart) without manual copy/paste between app and terminal

Edition boundary

• Community/public builds keep only paid feature stubs (src/loopbox/ee.rs) and do not ship Docker management implementation.
• Paid Docker/capability/runtime implementation is applied via private overlay assembly.

Agent API

Loopbox exposes a local API for agent clients while the app is running.

• Discovery file: ~/.config/loopbox/agent-api.json
• Token file: ~/.config/loopbox/agent-api-token (when auth is enabled)
• Default URL: http://127.0.0.1:39393
• OpenAPI endpoint: /v1/openapi.json (auto-generated at runtime)
• Edit enable/auth/port in Settings → Agent API

See docs/agent-api.md for endpoint and curl examples.

Quick Start

Prerequisites: macOS, Rust toolchain, Dioxus CLI

cargo run
# or with hot-reload:
dx serve --platform desktop

1. Click New Sandbox → pick a project directory
2. Add services or hit Auto Detect to fill from package.json scripts
3. System → Setup System → confirm the admin prompt (one-time, reversible)
4. Start services, open URLs, tail logs

Config

~/.config/loopbox/config.toml

[global]
domain_suffix = "localhost"
ip_base = "127.0.0."
ip_range_start = 2
ip_range_end = 254

[projects.myapp]
dir = "/Users/you/dev/myapp"
ip = "127.0.0.2"
default_open_service = "frontend"
grpc_proto_paths = ["./proto", "./apps/gateway/proto"]

[[projects.myapp.services]]
name = "backend"
command = "pnpm dev"
workdir = "/Users/you/dev/myapp/apps/backend"
env_files = [".env", ".env.local"]

[[projects.myapp.services.ports]]
port = 8080
protocol = "http1"
health_path = "/health"

[[projects.myapp.services]]
name = "gateway"
command = "go run ./cmd/gateway"
workdir = "/Users/you/dev/myapp"

[[projects.myapp.services.ports]]
port = 50051
protocol = "grpc_h2c"
health_path = "my.package.Gateway"

[[projects.myapp.services.ports]]
port = 8081
protocol = "http1"

[[projects.myapp.proxy_endpoints]]
name = "gateway-grpc-alias"
listen_host = "127.0.0.1"
listen_port = 50060
protocol = "grpc_h2c"
authority = "gateway.internal.localhost"
upstream_host = "127.0.0.2"
upstream_port = 50051
service_name = "gateway"

Service protocols: http1, grpc_h2c, tcp_passthrough.

Loopbox still accepts legacy single-port service fields (port, protocol, health_path) and normalizes them into services.ports on save/load.

For gRPC payload decoding in private builds, configure grpc_proto_paths and ensure protoc is available in your PATH.

Traffic capture options ([global.proxy_traffic]) may be ignored in this public core build.

Tech Stack

Language	Rust 2021
UI	Dioxus 0.7 (native desktop)
Async	Tokio
Config	TOML (~/.config/loopbox/)
Styling	Tailwind CSS, Sora + JetBrains Mono
Platform	macOS (loopback aliases, osascript, Terminal.app)

Build

dx build --platform desktop --release
dx bundle --platform macos --package-types dmg --release

Author

Niklas Schmidt — niklasschmidt.dev | niklas@niklasschmidt.dev

License

Loopbox is MIT licensed (LICENSE) and free for personal and commercial use.