Quickstart
This is the path I recommend when you run bhatti on a machine you own — a Linux box with KVM or an Apple Silicon Mac. You’ll use the CLI on that same machine to create a Linux VM. For hardware and service setup, see Self-hosting.
Install
Section titled “Install”curl -fsSL bhatti.sh/install | sudo bashThe installer needs root on both platforms. It downloads the CLI, runtime bundle and default rootfs tier, starts a systemd service on Linux or a launchd service on macOS, and creates an admin API key. It saves the key in your invoking user’s ~/.bhatti/config.yaml and prints it once. Save the key securely.
Fresh installs expose the control API on <data_dir>/api.sock, not on a public TCP port. The installer gives the bhatti group access to the socket; the CLI uses it locally and still authenticates every request with your API key. You do not need to run bhatti setup on this machine. If your shell can’t connect, see Self-hosting → Local API access.
Create and use a sandbox
Section titled “Create and use a sandbox”bhatti create --name devbhatti exec dev -- echo hello# → hellobhatti shell devDefaults are 1 vCPU and 1024 MB. The -- separates CLI flags from the command to run; it’s optional when there’s no ambiguity. bhatti shell attaches an interactive PTY; press Ctrl+\ to detach. The sandbox is a real Linux VM with its own kernel and copy-on-write disk — no network device by default. Your host CLI can still exec commands and transfer files over the authenticated API.
When you need internet access inside the sandbox, choose a policy explicitly at creation:
bhatti create --name online --net # public egress# Or restrict a workload to specific destinations:bhatti create --name agent --allow-host api.openai.com --allow-host github.comFor the distinction between --net, --egress, --allow-host, --allow-cidr, and sibling access, see Networking. Run an agent in a sandbox puts these pieces together.
Reach a service
Section titled “Reach a service”Start a service in the sandbox and publish its port:
bhatti exec dev -- bash -c 'python3 -m http.server 3000 &'bhatti publish dev -p 3000 -a my-appOn a socket-only install, publish does not mint a public https://my-app.bhatti.sh URL. With neither domain mode nor a separate public_proxy_listen configured, it supplies an authenticated local API proxy path; you need the API key to reach it. For a public HTTPS alias such as https://my-app.yourdomain.com, configure a domain first. Without domain mode, public_proxy_listen can instead expose unauthenticated path-based HTTP URLs for development/testing. Guest outbound networking is separate: a no-NIC sandbox can still serve a port through the host proxy. Keep a private service private rather than publishing it publicly.
Clean up
Section titled “Clean up”bhatti destroy devbhatti destroy onlinebhatti destroy agent-y skips the confirmation prompt. Destroy removes each sandbox’s disk overlay; a network-enabled sandbox used the owner’s shared gateway, not a gateway dedicated to that VM. When idle, a running sandbox may pause (warm), then power off (cold): disk persists but processes and /tmp do not. For a durable memory checkpoint, take an explicit snapshot; for stopped-service restart behavior, see Durability.
Drive the server from another machine
Section titled “Drive the server from another machine”A local Unix socket cannot be reached from your laptop over the network. Self-hosting → Remote access covers the two options: configure a domain with TLS for an HTTPS API endpoint, or SSH into the host and run its locally configured CLI. Do not expose an unauthenticated or plaintext API port to the internet. To give another agent or person a separate key, see Users & Auth.
Next steps
Section titled “Next steps”- Concepts — owners, sandboxes, networking and thermal states
- Self-hosting — service, socket permissions, remote access and backups
bhatti createandbhatti exec— full CLI options