### bhatti setup configuration file example

Source: https://bhatti.sh/docs/reference/cli/admin/setup

Example of the bhatti configuration file after running the setup command.

```yaml
api_url: https://api.bhatti.sh
auth_token: bht_abc123def456...
```

--------------------------------

### Setup btrfs loopback filesystem

Source: https://bhatti.sh/docs/self-hosting

Prepares a btrfs filesystem using a loopback file for bhatti's data directory. This ensures optimal performance with features like CoW clones and compression. It's recommended to run this before the install script.

```bash
sudo fallocate -l 500G /var/lib/bhatti-btrfs.img
sudo mkfs.btrfs -f /var/lib/bhatti-btrfs.img
sudo mkdir -p /var/lib/bhatti
sudo mount -o loop,noatime,compress=zstd:1 \
     /var/lib/bhatti-btrfs.img /var/lib/bhatti
echo '/var/lib/bhatti-btrfs.img /var/lib/bhatti btrfs loop,noatime,compress=zstd:1 0 0' \
     | sudo tee -a /etc/fstab
```

--------------------------------

### Setup for Cross-Architecture Builds with Buildx

Source: https://bhatti.sh/docs/managing/tiers/docker

This sequence of commands prepares your environment for cross-architecture builds. It installs the necessary binfmt_misc handlers and creates a new buildx builder instance.

```bash
bhatti exec dev -- docker run --privileged --rm tonistiigi/binfmt --install all
```

```bash
bhatti exec dev -- docker buildx create --use --name xb --driver docker-container
```

```bash
bhatti exec dev -- docker buildx build --platform linux/amd64,linux/arm64 \
    -t me/app:multi --push .
```

--------------------------------

### Restore a volume from a backup

Source: https://bhatti.sh/docs/reference/cli/volumes/restore

This example shows the complete process of stopping the development environment, listing available backups, restoring a specific volume from a backup, and then starting the development environment again.

```bash
bhatti stop dev
bhatti volume backup-list workspace
bhatti volume restore workspace --backup-id bk_a1b2c3d4
bhatti start dev
```

--------------------------------

### Start bhatti Daemon (Systemd)

Source: https://bhatti.sh/docs/reference/cli/admin/serve

For production environments, it is recommended to run bhatti as a systemd service. This involves starting the service and then viewing its logs.

```bash
sudo systemctl start bhatti
sudo journalctl -u bhatti -f
```

--------------------------------

### bhatti setup CLI command synopsis

Source: https://bhatti.sh/docs/reference/cli/admin/setup

This is the synopsis for the bhatti setup command, showing available flags.

```bash
bhatti setup [—url URL] [—token KEY]
```

--------------------------------

### User creation output and remote setup

Source: https://bhatti.sh/docs/reference/cli/admin/user-create

This shows the expected output after creating a user, including their ID, name, subnet, and API key. It also provides an example of how to use the generated token for remote CLI access.

```text
User created:
  ID:       usr_a1b2c3d4
  Name:     alice
  Subnet:   2
  API key:  bht_abc123def456...


This key will not be shown again. Save it now.


For remote CLI use:
  bhatti setup --url https://your-server:8080 --token bht_abc123def456...
```

--------------------------------

### Simulating systemctl start command

Source: https://bhatti.sh/docs/under-the-hood/lohar-the-blacksmith

This output shows the expected behavior when package scripts attempt to start a service using systemctl on a system where it is not present. The shim intercepts these calls to prevent installation failures.

```bash
Setting up openssh-server (1:9.6p1-3ubuntu13.5) ...
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of start.
ssh.service is a disabled or a static unit, not starting it.

```

--------------------------------

### Start bhatti Daemon (Foreground)

Source: https://bhatti.sh/docs/reference/cli/admin/serve

Use this command to start the bhatti daemon in the foreground, typically for development purposes. Ensure you have root privileges.

```bash
sudo bhatti serve
```

--------------------------------

### Configuration Precedence Example

Source: https://bhatti.sh/docs/reference/cli

Illustrates the order of precedence for configuration settings, from per-call flags to built-in defaults.

```bash
--url <x>            (highest)
api_url: <x>         (in config file)
BHATTI_URL=<x>       (env var)
http://localhost:8080 (default, lowest)

```

--------------------------------

### Install Docker Buildx Plugin

Source: https://bhatti.sh/docs/managing/tiers/docker

If the 'docker buildx' command is not recognized, it may be due to the docker-buildx-plugin not being installed. Use this command to install it.

```bash
sudo apt-get install -y docker-buildx-plugin
```

--------------------------------

### Interactive bhatti setup

Source: https://bhatti.sh/docs/reference/cli/admin/setup

Run bhatti setup interactively to configure the API endpoint and token. The command prompts for input and masks the token.

```bash
bhatti setup

API endpoint [http://localhost:8080]: https://api.bhatti.sh
API key: <input is hidden>
Saved to /home/alice/.bhatti/config.yaml
Testing connection... ✓ authenticated (3 sandboxes)
```

--------------------------------

### Build a custom environment, then save it

Source: https://bhatti.sh/docs/reference/cli/images/save

Create a sandbox, install Node.js and pnpm, then save the filesystem as a new image named 'node-app'.

```bash
bhatti create --name build --image minimal
bhatti exec build -- apt-get update && apt-get install -y nodejs
bhatti exec build -- npm install -g pnpm

bhatti image save build --name node-app
# saved "node-app" (512MB)
```

--------------------------------

### Lohar's systemctl shim: service start logic

Source: https://bhatti.sh/docs/under-the-hood/lohar-the-blacksmith

This snippet illustrates the service start logic within Lohar's systemctl shim. It involves parsing unit files, resolving user/group directives, setting up the environment, and executing the service binary.

```go
// cmd/lohar/systemctl.go:745-823
// ...
	case "start":
		// Parse unit file, find ExecStart, User, Group, Environment, etc.
		// Drop privileges if User/Group are specified
		// Set up environment variables from Environment= and EnvironmentFile=
		// Execute the binary specified in ExecStart
		fmt.Printf("shim: starting service %s\n", unit)
		// In a real implementation, this would involve os/exec and syscalls
		// For example: cmd := exec.Command("/path/to/binary", "arg1")
		// cmd.SysProcAttr = &syscall.SysProcAttr{ Setgid: true, Setuid: true }
		// cmd.Env = append(os.Environ(), "VAR=value")
		// err := cmd.Start()
		// if err != nil { return fmt.Errorf("failed to start service: %w", err) }
		// Store PID, etc.
		return nil
// ...

```

--------------------------------

### Install Bhatti with Docker and Browser Tier

Source: https://bhatti.sh/docs/self-hosting

Installs Bhatti using Docker, including the browser tier for enhanced functionality. The `--tier` flag sets the default tier for `bhatti create`, while `--tiers` installs additional tiers.

```bash
curl -fsSL bhatti.sh/install | sudo bash -s -- --tier docker --tiers browser
```

--------------------------------

### List VM Snapshots with JSON Output

Source: https://bhatti.sh/docs/reference/cli/snapshots/list

Use the --json flag with 'bhatti snapshot list' to get output in JSON format, suitable for scripting. This example filters the JSON output to show snapshots originating from the 'base' sandbox.

```bash
# JSON for scripting
bhatti snapshot list --json | jq '.[] | select(.source_sandbox == "base")'
```

--------------------------------

### Execute Command in Sandbox

Source: https://bhatti.sh/docs/reference/cli/sandbox

Executes a command within a running sandbox. This example installs npm packages.

```bash
bhatti exec dev -- npm install
```

--------------------------------

### Example: Listing Backups for 'workspace'

Source: https://bhatti.sh/docs/reference/cli/volumes/backup-list

Demonstrates the output format when listing backups for the 'workspace' volume. Shows backup ID, size, and creation timestamp.

```bash
bhatti volume backup-list workspace
```

--------------------------------

### Install Bhatti Daemon

Source: https://bhatti.sh/docs/quickstart

Installs the Bhatti daemon, lohar, Firecracker, kernel, and a minimal Ubuntu rootfs. It also sets up the systemd service and configures the CLI.

```bash
curl -fsSL bhatti.sh/install | sudo bash
```

--------------------------------

### Example of Rotating User API Key

Source: https://bhatti.sh/docs/reference/cli/admin/user-rotate-key

Example of executing the rotate-key command for a user named 'alice'. The output confirms the rotation and displays the new key, which should be saved immediately.

```bash
sudo bhatti user rotate-key alice
```

--------------------------------

### Start a sandbox

Source: https://bhatti.sh/docs/reference/cli/sandbox/start

Use this command to resume a sandbox from its on-disk snapshot. The VM continues exactly where it left off.

```bash
bhatti start dev
```

--------------------------------

### Install Bhatti CLI and Configure Remote Server

Source: https://bhatti.sh/docs/quickstart

Installs the Bhatti CLI on your local machine without sudo and configures it to connect to a remote Bhatti server using a provided URL and token.

```bash
curl -fsSL bhatti.sh/install | bash
```

```bash
bhatti setup --url https://your-server:8080 --token bht_abc...
```

```bash
bhatti setup
```

--------------------------------

### Start the bhatti daemon

Source: https://bhatti.sh/docs/reference/cli

Launch the bhatti daemon process, which manages sandboxes and serves the API.

```bash
bhatti serve
```

--------------------------------

### Create and Configure Minimal Tier

Source: https://bhatti.sh/docs/managing/tiers

Create a new tier using the 'minimal' image, update packages, install services, and check their status.

```bash
bhatti create --name dev --image minimal
bhatti exec dev -- sudo apt-get update
bhatti exec dev -- sudo apt-get install -y postgresql redis-server
bhatti exec dev -- systemctl status postgresql redis-server
```

--------------------------------

### Firecracker Boot Sequence: Instance Start Action

Source: https://bhatti.sh/docs/under-the-hood/engine

Initiates the startup of the configured microVM instance. This is the final action in the Firecracker boot sequence.

```json
10. Start the instance
    PUT /actions
    {"action_type":"InstanceStart"}
```

--------------------------------

### Example Output of bhatti ps

Source: https://bhatti.sh/docs/reference/cli/exec/ps

This is an example of the tabular output from 'bhatti ps', showing session ID, command, running status, and attachment status for each active session.

```bash
ID         COMMAND                                  RUNNING  ATTACHED
init       npm install && npm run dev               true     false
s1         /bin/zsh -li                             true     true
s2         ./long-running-worker.sh                 true     false
```

--------------------------------

### Human-readable output example

Source: https://bhatti.sh/docs/reference/cli/files/ls

Example of the human-readable output format, showing directory flag, mode, size, and name for each entry.

```text
drwxr-xr-x     4096 node_modules
-rw-r--r--     1234 app.js
-rw-r--r--      256 package.json
-rw-r--r--      512 README.md
```

--------------------------------

### JSON output example

Source: https://bhatti.sh/docs/reference/cli/volumes/list

An example of the JSON output when using the `--json` flag, showing volume name and attachment details.

```json
{
  "name": "workspace",
  "attachments": [
    {"sandbox_id": "abc123", "mount": "/workspace", "read_only": false}
  ]
}
```

--------------------------------

### Shell Completion Setup

Source: https://bhatti.sh/docs/reference/cli

Provides commands to set up shell completion for Bhatti CLI in bash, zsh, and fish shells.

```bash
bhatti completion bash > /etc/bash_completion.d/bhatti
bhatti completion zsh  > "${fpath[1]}/_bhatti"
bhatti completion fish > ~/.config/fish/completions/bhatti.fish

```

--------------------------------

### Example Share URL

Source: https://bhatti.sh/docs/reference/cli/networking/share

This is an example of the URL generated by 'bhatti share dev'. The URL contains a token in the fragment that grants shell access to the specified sandbox.

```text
https://api.bhatti.sh/_shell/a1b2c3d4#token=k3m9x2qr...
```

--------------------------------

### Install Bhatti CLI on User Machine

Source: https://bhatti.sh/docs/self-hosting

Installs the Bhatti CLI on a user's machine without requiring sudo privileges. This is the first step before configuring the CLI to connect to the server.

```bash
# CLI only, no sudo
curl -fsSL bhatti.sh/install | bash
```

--------------------------------

### Version output with server information

Source: https://bhatti.sh/docs/reference/cli/admin/version

Example output of `bhatti version` showing the CLI version, API endpoint, and server version when they are all up-to-date.

```bash
bhatti v1.10.0
api: https://api.bhatti.sh
server: v1.10.0

```

--------------------------------

### View bhatti admin status output example

Source: https://bhatti.sh/docs/reference/cli/admin/admin-status

An example of the output generated by the 'sudo bhatti admin status' command, showing version, host stats, sandbox and user totals, API/proxy counters, per-user breakdown, and recent events.

```text
Bhatti v1.10.0
Host: 0.42 load, 12.4 / 32.0 GB memory


Sandboxes  17 total (4 hot, 6 warm, 7 cold)
Users      8 total, 5 active
API        184.2K requests, 423 errors, 12 auth failures
Proxy      47.1K requests, 89 errors, 156 cold wakes


USER             SANDBOXES    STATUS
alice            3/10         2 running, 1 stopped
bob              0/5          -
worker-bot       5/5          5 running


RECENT EVENTS
  14:22:18  thermal.pause            alice        scraper          idle=180s
  14:21:45  sandbox.created          bob          test-1           cpus=2 mem=1024 image=minimal
  14:20:11  proxy.error              -            staging          alias=staging status=502
  14:18:33  thermal.wake             alice        api              from=cold 47ms
  ...

```

--------------------------------

### Install fish completion script

Source: https://bhatti.sh/docs/reference/cli/admin/completion

Prints the fish completion script to stdout and redirects it to the standard completions directory for fish.

```fish
bhatti completion fish > ~/.config/fish/completions/bhatti.fish
```

--------------------------------

### Non-interactive bhatti setup for agents and CI

Source: https://bhatti.sh/docs/reference/cli/admin/setup

Use bhatti setup with --url and --token flags for non-interactive configuration, suitable for agents, CI scripts, and provisioning tools.

```bash
bhatti setup --url https://api.bhatti.sh --token bht_abc123

Saved to /home/alice/.bhatti/config.yaml
Testing connection... ✓ authenticated (3 sandboxes)
```

--------------------------------

### Server Configuration Example

Source: https://bhatti.sh/docs/reference/config

A typical server configuration file for bhatti. This includes settings for the engine, listening address, data directory, and Firecracker-specific paths.

```yaml
engine: firecracker
listen: :8080
data_dir: /var/lib/bhatti


firecracker_bin: /usr/local/bin/firecracker
firecracker_jailer: /usr/local/bin/jailer
jail_uid: 10000
jail_gid: 10000
firecracker_kernel: /var/lib/bhatti/images/vmlinux-arm64
firecracker_rootfs: /var/lib/bhatti/images/rootfs-minimal-arm64.ext4

```

--------------------------------

### Check binfmt_misc Handlers

Source: https://bhatti.sh/docs/managing/tiers/docker

After running 'tonistiigi/binfmt --install all', verify that the necessary qemu handlers for cross-architecture builds are registered in /proc/sys/fs/binfmt_misc.

```bash
ls /proc/sys/fs/binfmt_misc/
```

--------------------------------

### Save Configured Sandbox as Image

Source: https://bhatti.sh/docs/managing/images

Create a custom image from a configured sandbox by installing software and then using 'bhatti image save'. This captures the root filesystem with your installed tools.

```bash
bhatti create --name build --image minimal
bhatti exec build -- apt-get update && apt-get install -y nodejs pnpm
bhatti exec build -- pnpm install -g some-tool

bhatti image save build --name node-stack
```

--------------------------------

### Example: Output format for bhatti ports

Source: https://bhatti.sh/docs/reference/cli/exec/ports

Shows the typical output format when listing ports for a sandbox, including the PORT and URL columns.

```text
PORT     URL
3000     http://localhost:8080/sandboxes/dev/proxy/3000/
6379     http://localhost:8080/sandboxes/dev/proxy/6379/
```

--------------------------------

### Install bash completion script system-wide

Source: https://bhatti.sh/docs/reference/cli/admin/completion

Prints the bash completion script to stdout and pipes it to tee to save it system-wide. Requires sudo.

```bash
bhatti completion bash | sudo tee /etc/bash_completion.d/bhatti > /dev/null
```

--------------------------------

### Install Bhatti CLI and Configure Remote Access

Source: https://bhatti.sh/docs

Installs only the Bhatti CLI binary on a local machine and configures it to connect to a remote Bhatti daemon. This is useful for managing a server from your laptop or in CI environments.

```bash
# Install the CLI binary
curl -fsSL bhatti.sh/install | bash


# Configure the endpoint and key
bhatti setup --url https://your-server:8080 --token bht_abc...
# or interactively:
bhatti setup
```

--------------------------------

### One-shot system overview (server-only)

Source: https://bhatti.sh/docs/reference/cli

Get a comprehensive overview of the bhatti system's status. This command is for server administration.

```bash
bhatti admin status
```

--------------------------------

### Start Sandbox from Snapshot

Source: https://bhatti.sh/docs/reference/cli/sandbox

Resumes a sandbox from its last saved snapshot, continuing exactly where it left off.

```bash
bhatti start dev                      # resume from where it stopped
```

--------------------------------

### Execute Docker Buildx Build (Same Architecture)

Source: https://bhatti.sh/docs/managing/tiers/docker

Use this command for native, same-architecture builds with Docker and buildx. No special setup is required.

```bash
bhatti exec dev -- docker buildx build -t me/app:latest .
```

--------------------------------

### Volume Backup with Sandbox Stop/Start

Source: https://bhatti.sh/docs/reference/cli/volumes/backup

To ensure a consistent backup, stop the sandbox before backing up the volume, and then start it again. This flushes guest writes and detaches the volume.

```bash
bhatti stop dev          # detaches volume, flushes guest writes
bhatti volume backup workspace
bhatti start dev         # resume
```

--------------------------------

### Backup Creation Confirmation

Source: https://bhatti.sh/docs/reference/cli/volumes/backup

This is an example of the output received after a successful backup operation, indicating the backup record details.

```bash
backup bk_a1b2c3d4 created (workspace, 5234567890 bytes)
```

--------------------------------

### Example: List ports for 'dev' sandbox

Source: https://bhatti.sh/docs/reference/cli/exec/ports

Demonstrates how to list the listening ports for the 'dev' sandbox. The output includes the port number and a corresponding proxy URL.

```bash
bhatti ports dev
```

--------------------------------

### Example: Get Latest Backup ID using JSON Output

Source: https://bhatti.sh/docs/reference/cli/volumes/backup-list

Retrieves the ID of the most recent backup for a volume by piping the JSON output to `jq`. This is useful for scripting and automation.

```bash
# Latest backup ID
bhatti volume backup-list workspace --json | jq -r 'sort_by(.created_at) | last | .id'
```

--------------------------------

### Sandbox Corrupt Error Message

Source: https://bhatti.sh/docs/under-the-hood/thermal-states

This is an example of an error message indicating that a sandbox snapshot is corrupt. It suggests using 'bhatti start --force' to retry or destroying and recreating the sandbox.

```text
Error: sandbox "dev" snapshot is corrupt: <reason> —
use 'bhatti start --force' to retry or destroy and recreate
(volume data is safe).
```

--------------------------------

### State Transition Logic in Server

Source: https://bhatti.sh/docs/under-the-hood/thermal-states

Illustrates the logic for pausing a VM and adjusting the virtio-balloon to reclaim host RAM when transitioning from Hot to Warm state.

```go
PATCH /vm {"state":"Paused"} to Firecracker’s API. The vCPU pause is single-digit milliseconds.
Inflate the virtio-balloon to ~50% of guest memory (pkg/server/server.go:626-632). The host gets that RAM back immediately — the balloon driver in the guest hands free pages back to the host.
Record the pause time as the sandbox’s last-activity timestamp. The warm-to-cold timer starts from now, not from your last exec.

```

--------------------------------

### Example: Deleting a User

Source: https://bhatti.sh/docs/reference/cli/admin/user-delete

Demonstrates the process of deleting a user named 'alice', including the confirmation prompt and successful deletion message.

```bash
sudo bhatti user delete alice
```

```text
Delete user "alice"? [y/N]: y
deleted user "alice"
```

--------------------------------

### Clone a volume for an experiment

Source: https://bhatti.sh/docs/reference/cli/volumes/clone

This example demonstrates cloning a volume named 'workspace' to 'workspace-experiment' and then creating a new sandbox named 'experiment' that uses the cloned volume.

```bash
# Fork for an experiment
bhatti volume clone workspace --name workspace-experiment
bhatti create --name experiment --volume workspace-experiment:/workspace

```

--------------------------------

### Create and Run Docker Container

Source: https://bhatti.sh/docs/managing/tiers/docker

Demonstrates how to create a Docker tier microVM and execute a simple Docker command within it.

```bash
bhatti create --name ci --image docker --cpus 4 --memory 4096
bhatti exec ci -- docker run hello-world
```

--------------------------------

### Install or Update Bhatti via Curl

Source: https://bhatti.sh/docs/updating

Use these commands to install or update Bhatti if your server version is older than v1.7.3 or for a fresh installation.

```bash
curl -fsSL bhatti.sh/install | bash
```

```bash
curl -fsSL bhatti.sh/install | sudo bash
```

--------------------------------

### Create Sandbox with Custom Resources and Init Script

Source: https://bhatti.sh/docs/reference/cli/sandbox/create

Creates a sandbox with specified CPU and memory, custom environment variables, and an initialization script to run commands on boot.

```bash
bhatti create --name api \
  --cpus 2 --memory 2048 \
  --env NODE_ENV=production,LOG_LEVEL=info \
  --init "cd /workspace && npm install"
```

--------------------------------

### Create a new sandbox VM

Source: https://bhatti.sh/docs/reference/cli

Use the `create` command to provision a new sandbox environment.

```bash
bhatti create [flags]
```

--------------------------------

### Install bash completion script per-user

Source: https://bhatti.sh/docs/reference/cli/admin/completion

Sources the bash completion script from stdout directly into the user's bashrc file. No sudo required.

```bash
echo 'source <(bhatti completion bash)' >> ~/.bashrc
```

--------------------------------

### Quick test against a service inside the sandbox

Source: https://bhatti.sh/docs/reference/cli/exec/ports

This example shows how to perform a quick test against a service running inside the sandbox. It extracts the first proxy URL from the JSON output and uses curl to send a request, including authorization.

```bash
# Quick test against a service inside the sandbox
bhatti ports dev --json | jq -r '.[] | .proxy_url' | head -1 | xargs curl -H "Authorization: Bearer $BHATTI_TOKEN"
```

--------------------------------

### Create Computer Tier Sandbox with Custom Environment Variables

Source: https://bhatti.sh/docs/managing/tiers/computer

Create a sandbox with specific display dimensions and frame rate settings using environment variables.

```bash
bhatti create --name desk --image computer --cpus 4 --memory 4096 \
    --env "DISPLAY_WIDTH=1920,DISPLAY_HEIGHT=1080,KASM_FRAMERATE=30"
```

--------------------------------

### Retry a failed sandbox start

Source: https://bhatti.sh/docs/reference/cli/sandbox/start

If a previous restore failed, use the --force flag to retry the start operation after fixing the underlying issue.

```bash
bhatti start dev --force
```

--------------------------------

### Non-interactive bhatti install with all tiers

Source: https://bhatti.sh/docs/self-hosting

Installs bhatti non-interactively, including all available rootfs tiers. This allows for flexibility in creating sandboxes with different pre-configured environments.

```bash
# Default minimal, plus install every other tier
curl -fsSL bhatti.sh/install | sudo bash -s -- --tiers all
```

--------------------------------

### Create a Sandbox

Source: https://bhatti.sh/docs/quickstart

Creates a new sandbox with default settings (1 vCPU, 1024 MB memory). You can override these defaults using --cpus and --memory flags.

```bash
bhatti create --name dev
```

--------------------------------

### Pinning systemd to Prevent Installation

Source: https://bhatti.sh/docs/under-the-hood/lohar-the-blacksmith

This configuration prevents the installation of systemd and related packages by setting their APT pin priority to -1. This is crucial for environments where systemd should not be present.

```bash
printf "Package: systemd systemd-sysv systemd-resolved\nPin: release *\nPin-Priority: -1\n" > /etc/apt/preferences.d/no-systemd-daemon
```

--------------------------------

### Create Sandbox Injecting a Local Config File

Source: https://bhatti.sh/docs/reference/cli/sandbox/create

Creates a sandbox and injects a local configuration file into a specified guest path during boot. The file is read from the local system at submit time.

```bash
bhatti create --name worker --file ./config.json:/etc/worker/config.json
```

--------------------------------

### Agent Helper Script Execution Example

Source: https://bhatti.sh/docs/managing/tiers/computer

Demonstrates a typical agent loop using `bhatti exec` to launch Chromium, take a screenshot, simulate key presses, and type text.

```bash
bhatti exec desk -- chromium-browser https://example.com &
sleep 2
bhatti exec desk -- screenshot --base64 > frame.b64
bhatti exec desk -- xdotool key Return
bhatti exec desk -- xdotool type "hello world"
```

--------------------------------

### Non-interactive bhatti install with specific tier

Source: https://bhatti.sh/docs/self-hosting

Installs bhatti non-interactively, setting a specific rootfs tier (e.g., 'browser') as the default. Useful for automation with tools like Ansible or Packer.

```bash
# Specific tier as the default
curl -fsSL bhatti.sh/install | sudo bash -s -- --tier browser
```

--------------------------------

### Lohar's systemctl shim: boot service startup

Source: https://bhatti.sh/docs/under-the-hood/lohar-the-blacksmith

This snippet shows how Lohar's systemctl shim starts enabled services at boot. It reads the `multi-user.target.wants/` directory and initiates the startup sequence for each enabled service.

```go
// cmd/lohar/systemctl.go:1318
func startEnabledServices() {
	fmt.Println("shim: starting enabled services at boot...")
	// Read directory like /etc/systemd/system/multi-user.target.wants/
	// For each symlink found (e.g., postgresql.service),
	// call the internal 'start' logic for that unit.
}

```

--------------------------------

### Bootstrap a New User

Source: https://bhatti.sh/docs/reference/cli/admin

Creates a new user on the bhatti server with a specified name and maximum number of sandboxes. Requires root privileges.

```bash
sudo bhatti user create --name alice --max-sandboxes 10
```

--------------------------------

### Example Firecracker Rate Limiter Configuration

Source: https://bhatti.sh/docs/under-the-hood/engine

Provides example configuration values for Firecracker rate limiters in a multi-tenant deployment. These values set hard ceilings for network and disk I/O to prevent resource saturation.

```yaml
firecracker:
  rate_limits:
    net_bandwidth: 12500000   # 100 Mbps per direction
    net_burst: 10000000       # 10 MB burst
    disk_bandwidth: 104857600 # 100 MB/s
    disk_iops: 10000          # 10K ops/s

```

--------------------------------

### Get a snapshot

Source: https://bhatti.sh/docs/reference/api

Retrieves details for a specific snapshot.

```bash
GET /snapshots/:name
```

--------------------------------

### Get an image

Source: https://bhatti.sh/docs/reference/api

Retrieves details for a specific image.

```bash
GET /images/:name
```

--------------------------------

### List images with example output

Source: https://bhatti.sh/docs/reference/cli/images/list

Demonstrates the output format of the bhatti image list command, showing image details like ID, name, source, size, and scope.

```bash
ID                   NAME                 SOURCE                         SIZE       SCOPE
img_abc123           minimal              built-in                       186MB      admin
img_def456           browser              built-in                       612MB      admin
img_ghi789           python-3.12          oci:python:3.12                284MB      user
img_jkl012           my-stack             snapshot:dev                   512MB      user
```

--------------------------------

### Get a template

Source: https://bhatti.sh/docs/reference/api

Retrieves a specific template by its ID.

```APIDOC
## GET /templates/:id

### Description
Retrieves a specific template by its ID.

### Method
GET

### Endpoint
`/templates/:id`
```

--------------------------------

### Get a snapshot

Source: https://bhatti.sh/docs/reference/api

Retrieves details for a specific snapshot by its name.

```APIDOC
## GET /snapshots/:name

### Description
Retrieves details for a specific snapshot by its name.

### Method
GET

### Endpoint
/snapshots/:name
```

--------------------------------

### Version output with update available notice

Source: https://bhatti.sh/docs/reference/cli/admin/version

Example output of `bhatti version` when a newer CLI version is available. It shows the current and latest versions and suggests running `bhatti update`.

```bash
bhatti v1.9.0
api: https://api.bhatti.sh
server: v1.10.0


Update available: v1.9.0 → v1.10.0 (bhatti update)

```

--------------------------------

### Get an image

Source: https://bhatti.sh/docs/reference/api

Retrieves details for a specific image by its name.

```APIDOC
## GET /images/:name

### Description
Retrieves details for a specific image by its name.

### Method
GET

### Endpoint
/images/:name
```

--------------------------------

### Unpublish Confirmation

Source: https://bhatti.sh/docs/reference/cli/networking/unpublish

This is an example of the output received after successfully unpublishing a port.

```text
Unpublished port 3000
```

--------------------------------

### Configure Remote Builders for CI

Source: https://bhatti.sh/docs/managing/tiers/docker

This example demonstrates setting up remote builders for a Continuous Integration pipeline, allowing buildx to orchestrate builds across different architectures on separate hosts.

```bash
# Driver machine — orchestrates two remote builders.
docker buildx create --name xb --platform linux/amd64 ssh://user@amd64-sandbox-host
docker buildx create --append --name xb --platform linux/arm64 ssh://user@arm64-sandbox-host
docker buildx use xb
docker buildx build --platform linux/amd64,linux/arm64 --push -t me/app:x .
```

--------------------------------

### Get a volume

Source: https://bhatti.sh/docs/reference/api

Retrieves details for a specific persistent volume by its name.

```APIDOC
## GET /volumes/:name

### Description
Retrieves details for a specific persistent volume by its name.

### Method
GET

### Endpoint
`/volumes/:name`
```

--------------------------------

### Create Sandboxes with Built-in Tiers

Source: https://bhatti.sh/docs/managing/images

Use the 'bhatti create' command to provision new sandboxes based on pre-defined tiers like 'browser' or 'docker'.

```bash
bhatti create --name scraper --image browser
bhatti create --name ci --image docker
```

--------------------------------

### GET /sandboxes/:id/ports

Source: https://bhatti.sh/docs/reference/api

Lists all listening ports for a specific sandbox.

```APIDOC
## GET /sandboxes/:id/ports

### Description
Lists all listening ports for a specific sandbox.

### Method
GET

### Endpoint
`/sandboxes/:id/ports`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the sandbox.

### Response
#### Success Response (200)
- **sandbox_id** (string) - The ID of the sandbox.
- **container_port** (integer) - The port number inside the container.
- **proxy_url** (string) - The path-relative URL to access the proxied port.

#### Response Example
```json
[
  {"sandbox_id": "a1b2c3d4", "container_port": 3000, "proxy_url": "/sandboxes/a1b2c3d4/proxy/3000/"}
]
```
```

--------------------------------

### GET /sandboxes/:id/sessions

Source: https://bhatti.sh/docs/reference/api

Lists all active sessions within a specific sandbox.

```APIDOC
## GET /sandboxes/:id/sessions

### Description
Lists all active sessions within a specific sandbox.

### Method
GET

### Endpoint
`/sandboxes/:id/sessions`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the sandbox.

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the session.
- **argv** (string) - The command used to start the session.
- **running** (boolean) - Indicates if the session is currently running.
- **attached** (boolean) - Indicates if a client is currently attached to the session.
- **created_at** (integer) - Timestamp of session creation.

#### Response Example
```json
[
  {"session_id": "init", "argv": "npm install", "running": true, "attached": false, "created_at": 1761792000},
  {"session_id": "s1", "argv": "/bin/zsh -li", "running": true, "attached": true, "created_at": 1761792100}
]
```
```

--------------------------------

### Get Volume Endpoint

Source: https://bhatti.sh/docs/reference/api

Retrieves detailed information about a specific persistent volume by its name.

```bash
GET /volumes/:name
```

--------------------------------

### Install All binfmt Handlers

Source: https://bhatti.sh/docs/managing/tiers/docker

This command registers handlers for various binary formats, which is crucial for enabling cross-architecture container builds. It is often necessary when cross-arch builds fail with 'exec format error'.

```bash
tonistiigi/binfmt --install all
```

--------------------------------

### GET /ports

Source: https://bhatti.sh/docs/reference/api

Lists all listening ports across all sandboxes owned by the authenticated user.

```APIDOC
## GET /ports

### Description
Lists all listening ports across all sandboxes owned by the authenticated user.

### Method
GET

### Endpoint
`/ports`

### Response
#### Success Response (200)
- **sandbox_id** (string) - The ID of the sandbox.
- **container_port** (integer) - The port number inside the container.
- **proxy_url** (string) - The path-relative URL to access the proxied port.

(Response shape is the same as `/sandboxes/:id/ports`)
```

--------------------------------

### Get a sandbox

Source: https://bhatti.sh/docs/reference/api

Retrieves the full sandbox record using either its name or ID.

```APIDOC
## GET /sandboxes/:id

### Description
Retrieves the full sandbox record using either its name or ID.

### Method
GET

### Endpoint
/sandboxes/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The name or ID of the sandbox.
```

--------------------------------

### Go helper utility for spawning daemons

Source: https://bhatti.sh/docs/under-the-hood/decisions

This Go code snippet illustrates a helper utility (`spawn`) that correctly places a process into a cgroup before executing the target daemon. This prevents issues with daemons that fork during startup.

```go
package main

import (
	"fmt"
	"os"
	"syscall"
)

func main() {
	if len(os.Args) < 2 {
		fmt.Fprintf(os.Stderr, "Usage: %s <daemon> [args...]\n", os.Args[0])
		os.Exit(1)
	}

	// Write self PID to cgroup.procs
	// This assumes the helper is already in the correct cgroup
	// For a more robust solution, explicitly open and write to the cgroup file.
	// Example (conceptual):
	// cgroupProcs, err := os.OpenFile("/sys/fs/cgroup/system.slice/kasmvnc.service/cgroup.procs", os.O_WRONLY, 0)
	// if err == nil {
	// 	defer cgroupProcs.Close()
	// 	_, err = fmt.Fprintf(cgroupProcs, "%d\n", os.Getpid())
	// 	if err != nil {
	// 		fmt.Fprintf(os.Stderr, "Failed to write PID to cgroup.procs: %v\n", err)
	// 		os.Exit(1)
	// 	}
	// } else {
	// 	fmt.Fprintf(os.Stderr, "Could not open cgroup.procs: %v\n", err)
	// 	// Decide how to handle this: exit or proceed without cgroup management
	// }

	// Execute the actual daemon
	err = syscall.Exec(os.Args[1], os.Args[1:], os.Environ())
	if err != nil {
		fmt.Fprintf(os.Stderr, "Failed to exec daemon %s: %v\n", os.Args[1], err)
		os.Exit(1)
	}
}

```

--------------------------------

### Scripted Volume Backup with JSON Output

Source: https://bhatti.sh/docs/reference/cli/volumes/backup

This example demonstrates how to capture the backup ID for scripting purposes by using the `--json` flag and piping the output to `jq`.

```bash
# JSON for scripting (capture the ID for later restore)
backup_id=$(bhatti volume backup workspace --json | jq -r .id)
echo "backed up: $backup_id"
```

--------------------------------

### Start a sandbox

Source: https://bhatti.sh/docs/reference/api

Restores a sandbox from its snapshot. The `force` option can retry even if the sandbox is in an unknown state.

```APIDOC
## POST /sandboxes/:id/start

### Description
Restores a sandbox from its snapshot. The `force` option can retry even if the sandbox is in an unknown state.

### Method
POST

### Endpoint
/sandboxes/:id/start

### Parameters
#### Path Parameters
- **id** (string) - Required - The name or ID of the sandbox.

#### Request Body
- **force** (bool) - Optional - Retries the start operation even if the sandbox is in an `unknown` state from a previously failed restore.
```

--------------------------------

### Create a Sandbox VM

Source: https://bhatti.sh/docs/reference/cli/sandbox

Creates a new sandbox VM with specified name, CPU, and memory. Other optional flags can configure environment variables, init scripts, volumes, secrets, and file injection.

```bash
bhatti create --name dev --cpus 2 --memory 1024
```

--------------------------------

### GET /sandboxes/:id/files?ls=true

Source: https://bhatti.sh/docs/reference/api

Lists the contents of a directory within a sandbox. Capped at 10,000 entries.

```APIDOC
## GET /sandboxes/:id/files?ls=true

### Description
Lists the contents of a directory within a sandbox. Capped at 10,000 entries.

### Method
GET

### Endpoint
`/sandboxes/:id/files`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the sandbox.

#### Query Parameters
- **path** (string) - Required - Absolute path inside the sandbox.
- **ls** (boolean) - Required - Set to `true` to list directory contents.

### Response
#### Success Response (200)
- **name** (string) - The name of the file or directory.
- **size** (integer) - The size in bytes.
- **mode** (string) - The file mode in octal format.
- **is_dir** (boolean) - Indicates if the entry is a directory.
- **mtime** (integer) - Timestamp of last modification.

#### Response Example
```json
[
  {"name": "app.js", "size": 1234, "mode": "0644", "is_dir": false, "mtime": 1761792345},
  {"name": "node_modules", "size": 4096, "mode": "0755", "is_dir": true, "mtime": 1761792500}
]
```
```

--------------------------------

### Create Sandboxes from Custom Image

Source: https://bhatti.sh/docs/managing/images

Provision new sandboxes using a custom image you previously saved. This ensures new sandboxes start with all the pre-installed software.

```bash
bhatti create --name worker-1 --image node-stack
bhatti create --name worker-2 --image node-stack
```

--------------------------------

### Create and Publish Computer Tier Sandbox

Source: https://bhatti.sh/docs/managing/tiers/computer

Use these commands to create a new sandbox with the 'computer' image, allocate resources, publish it to a specific port, and retrieve VNC credentials.

```bash
bhatti create --name desk --image computer --cpus 2 --memory 4096 --disk-size 8192
bhatti publish desk -p 6080
bhatti exec desk -- vnc-creds          # username + password
# Open the URL printed by `publish` in your browser, log in.
```

--------------------------------

### GET /sandboxes/:id/files

Source: https://bhatti.sh/docs/reference/api

Reads the content of a file within a sandbox. Supports offset and limit for partial reads.

```APIDOC
## GET /sandboxes/:id/files

### Description
Reads the content of a file within a sandbox. Supports offset and limit for partial reads.

### Method
GET

### Endpoint
`/sandboxes/:id/files`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the sandbox.

#### Query Parameters
- **path** (string) - Required - Absolute path inside the sandbox.
- **offset** (integer) - Optional - 1-indexed line number to start from.
- **limit** (integer) - Optional - Max lines to return.
- **max_bytes** (integer) - Optional - Max bytes to return.

### Response
#### Success Response (200)
Returns raw file content with `Content-Type: application/octet-stream`. The `X-File-Size` header carries the total size.

### Request Example
```bash
curl "http://localhost:8080/sandboxes/dev/files?path=/workspace/app.js" \
  -H "Authorization: Bearer $TOKEN" \
  -o app.js
```

**Server-side truncation:**
```bash
curl "http://localhost:8080/sandboxes/dev/files?path=/var/log/agent.log&offset=1&limit=2000&max_bytes=51200" \
  -H "Authorization: Bearer $TOKEN"
```
```

--------------------------------

### Basic Bhatti Operations

Source: https://bhatti.sh/docs/self-hosting

Demonstrates core Bhatti commands for creating, executing commands within, and destroying a sandbox. This verifies the daemon's health, agent reachability, and CLI configuration.

```bash
bhatti create --name test
bhatti exec test -- uname -a
bhatti destroy test
```

--------------------------------

### Update bhatti

Source: https://bhatti.sh/docs/reference/cli

Update the bhatti CLI or the entire bhatti installation. Options include updating only the CLI or specifying tiers.

```bash
bhatti update [--cli-only] [--tiers <list>]
```

--------------------------------

### Share a Sandbox

Source: https://bhatti.sh/docs/reference/cli/networking/share

Generates a shareable URL for the 'dev' sandbox. The recipient can access an interactive terminal in their browser without any installation.

```bash
bhatti share dev
```

--------------------------------

### Print CLI and server versions

Source: https://bhatti.sh/docs/reference/cli/admin/version

Run the `bhatti version` command to display the CLI version, API endpoint, and server version. This is useful for verifying your current setup.

```bash
bhatti version
```

--------------------------------

### Publish Sandbox with Custom Domain

Source: https://bhatti.sh/docs/managing/custom-domain

Create and publish a sandbox, then verify its accessibility via the custom domain URL.

```bash
bhatti create --name test
bhatti publish test -p 8080 -a hello
# → https://hello.yourdomain.com
```

--------------------------------

### Attempt to shrink a volume (fails)

Source: https://bhatti.sh/docs/reference/cli/volumes/resize

This example demonstrates that attempting to shrink a volume by providing a smaller size will result in an error.

```bash
bhatti volume resize workspace --size 1024
```