### Install Arrakis using Setup Script

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command downloads and executes the Arrakis setup script from GitHub. It installs the necessary components for running Arrakis on the GCE VM.

```shell
cd $HOME
curl -sSL "https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh" | bash
```

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

### Setup Arrakis with Prebuilt Binaries

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Installs Arrakis using a setup script that downloads prebuilt binaries and necessary images. After execution, it lists the contents of the 'arrakis-prebuilt' directory.

```bash
curl -sSL https://raw.githubusercontent.com/abshkbh/arrakis/main/setup/setup.sh | bash
ls arrakis-prebuilt
```

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

### Verify Arrakis Installation

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command navigates to the Arrakis prebuilt directory and lists its contents to verify that the installation was successful.

```bash
cd $HOME/arrakis-prebuilt
ls
```

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

### Run Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command starts the Arrakis client, which is used to interact with the Arrakis REST server and manage sandboxes.

```bash
cd ./arrakis-prebuilt
./arrakis-client
```

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

### Arrakis Python SDK Usage Example

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Demonstrates how to use the py-arrakis Python SDK to interact with Arrakis. This example shows starting a sandbox programmatically.

```python
from arrakis.client import ArrakisClient

client = ArrakisClient()

# Start a sandbox
sandbox = client.start_sandbox(name='my-agent-sandbox')
print(f"Sandbox started: {sandbox.id}")

# You can then upload files, execute commands, etc.
```

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

### Run Arrakis REST Server

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command starts the Arrakis REST server. It requires superuser privileges.

```bash
sudo ./arrakis-restserver
```

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

### Start a VM with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Starts a virtual machine with a specified name using the Arrakis CLI client. It returns metadata including the VM's IP address and status.

```bash
./out/arrakis-client start -n foo
```

```json
started VM: {"codeServerPort":"","ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
```

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

### Install Prerequisite Images

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Installs prerequisite images required for building and running the project using a Python script.

```bash
./setup/install-images.py
```

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

### Run Arrakis REST Server

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Starts the Arrakis REST API server. This command should be executed from the 'arrakis-prebuilt' directory after the setup script has been run.

```bash
cd arrakis-prebuilt
sudo ./arrakis-restserver
```

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

### Arrakis CLI VM Management

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Demonstrates common Arrakis CLI commands for managing virtual machines. This includes starting, listing, stopping, and destroying VMs, as well as snapshotting and restoring them. The examples show the command syntax and expected output.

```bash
./out/arrakis-client start -n foo
```

```json
started VM: {"codeServerPort":"","ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
```

```bash
ssh elara@10.20.1.2
```

```bash
./out/arrakis-client list -n foo
```

```json
VM: {"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
```

```bash
./out/arrakis-client list-all
```

```json
VMs: {"vms":[{"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}]}
```

```bash
./out/arrakis-client stop -n foo
```

```bash
./out/arrakis-client destroy -n foo
```

```bash
./out/arrakis-client snapshot -n foo-original -o foo-snapshot
```

```bash
./out/arrakis-client destroy -n foo-original -o foo-snapshot
```

```bash
./out/arrakis-client restore -n foo-original --snapshot foo-snapshot
```

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

### Start Arrakis REST Server

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Starts the Arrakis REST server. Root access is required for iptables configuration for guest networking.

```bash
sudo ./out/arrakis-restserver
```

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

### Install py-arrakis SDK

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Installs the Arrakis Python SDK using pip. This is the first step to interact with the arrakis-restserver.

```bash
pip install py-arrakis
```

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

### Install Golang Dependencies

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Ensures that all necessary Golang dependencies for the project are downloaded and managed.

```go
go mod tidy
```

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

### Create GCE VM with Nested Virtualization

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command creates a Google Compute Engine virtual machine instance with nested virtualization enabled. It specifies machine type, network settings, service account, scopes, disk configuration, and security features. Replace placeholders like $VM_NAME, $PROJECT_ID, $SERVICE_ACCOUNT, and $ZONE with your specific values.

```bash
VM_NAME=<your-vm-name>
PROJECT_ID=<your-project-id>
SERVICE_ACCOUNT=<your-service-account>
ZONE=<your-zone>

gcloud compute instances create ${VM_NAME} --project=${PROJECT_ID} --zone=${ZONE} --machine-type=n1-standard-1 --network-interface=network-tier=STANDARD,stack-type=IPV4_ONLY,subnet=default --maintenance-policy=MIGRATE --provisioning-model=STANDARD --service-account=${SERVICE_ACCOUNT} --scopes=https://www.googleapis.com/auth/devstorage.read_only,https://www.googleapis.com/auth/logging.write,https://www.googleapis.com/auth/monitoring.write,https://www.googleapis.com/auth/service.management.readonly,https://www.googleapis.com/auth/servicecontrol,https://www.googleapis.com/auth/trace.append --create-disk=auto-delete=yes,boot=yes,device-name=maverick-gcp-dev-vm3,image=projects/ubuntu-os-cloud/global/images/ubuntu-2204-jammy-v20250128,mode=rw,size=20,type=pd-standard --no-shielded-secure-boot --shielded-vtpm --shielded-integrity-monitoring --labels=goog-ec-src=vm_add-gcloud --reservation-affinity=any --enable-nested-virtualization
```

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

### VNC Connection Details Example

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

An example of the sandbox metadata response, highlighting the `port_forwards` field. It shows how to identify the VNC server's host port (e.g., '3000') from the 'gui' description.

```bash
{
  'name': 'agent-sandbox',
  'status': 'RUNNING',
  'ip': '10.20.1.2/24',
  'tap_device_name': 'tap0',
  'port_forwards': [{'host_port': '3000', 'guest_port': '5901', 'description': 'gui'}]
}
```

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

### Start an Arrakis Sandbox via CLI

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Initiates a new sandbox environment named 'agent-sandbox' using the Arrakis command-line interface. This command is executed from the 'arrakis-prebuilt' directory.

```bash
cd arrakis-prebuilt
./arrakis-client start -n agent-sandbox
```

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

### Run Commands in a Sandbox

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Demonstrates how to start a sandbox, run a command within it, and ensures the sandbox is automatically destroyed upon exiting the context. Requires an active arrakis-restserver.

```python
# Replace this with the ip:port where `arrakis-restserver` is running.
sandbox_manager = SandboxManager('http://127.0.0.1:7000')

# Start a new sandbox.
with sb as sandbox_manager.start_sandbox('agent-sandbox'):
  sb.run_cmd('echo hello world')
```

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

### Add Network Tag to GCE VM

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command adds a network tag to the specified GCE VM instance. This tag is used by firewall rules to control network traffic.

```bash
NETWORK_TAG=allow-ingress-ports
FIREWALL_RULE=allow-ingress-ports-rule
gcloud compute instances add-tags ${VM_NAME} --tags=${NETWORK_TAG} --zone=${ZONE}
```

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

### Create Firewall Rule for Arrakis Ports

Source: https://github.com/abshkbh/arrakis/blob/main/setup/gcp-instructions.md

This command creates a firewall rule to allow ingress traffic on TCP ports 3000-5000 and 7000 for VMs tagged with 'allow-ingress-ports'. This is necessary for Arrakis to function correctly.

```bash
FIREWALL_RULE=allow-ingress-ports-rule
gcloud compute firewall-rules create ${FIREWALL_RULE} \
--direction=INGRESS \
--priority=1000 \
--network=default \
--action=ALLOW \
--rules=tcp:3000-5000,tcp:7000 \
--source-ranges=0.0.0.0/0 \
--target-tags=${NETWORK_TAG} \
--description="Allow TCP ingress on ports 3000-5000 and 7000 for VMs with the ${NETWORK_TAG} tag"
```

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

### Arrakis REST API Specification

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

This section outlines the REST API provided by the arrakis-restserver. It details the available endpoints for managing VMs, such as starting, stopping, destroying, and listing them. The API specification is defined in the server-api.yaml file.

```APIDOC
OpenAPI Specification for Arrakis REST API

Base URL: /api/v1

Endpoints:

POST /vms
  Summary: Start a new VM.
  Description: Spawns a new virtual machine with the specified configuration.
  Request Body:
    content:
      application/json:
        schema:
          type: object
          properties:
            name: { type: string, description: Name of the VM }
            # ... other VM configuration parameters
  Responses:
    200 OK:
      description: VM started successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              vmName: { type: string }
              ip: { type: string }
              status: { type: string }
              # ... other VM metadata

GET /vms/{vmName}
  Summary: Get VM details.
  Description: Retrieves metadata and status for a specific VM.
  Parameters:
    - name: vmName
      in: path
      required: true
      schema: { type: string }
  Responses:
    200 OK:
      description: VM details retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              vmName: { type: string }
              ip: { type: string }
              status: { type: string }
              # ... other VM metadata

GET /vms
  Summary: List all VMs.
  Description: Returns a list of all managed virtual machines.
  Responses:
    200 OK:
      description: List of VMs.
      content:
        application/json:
          schema:
            type: object
            properties:
              vms:
                type: array
                items:
                  type: object
                  properties:
                    vmName: { type: string }
                    ip: { type: string }
                    status: { type: string }
                    # ... other VM metadata

DELETE /vms/{vmName}
  Summary: Stop and destroy a VM.
  Description: Terminates the specified virtual machine.
  Parameters:
    - name: vmName
      in: path
      required: true
      schema: { type: string }
  Responses:
    200 OK:
      description: VM stopped and destroyed.

POST /vms/{vmName}/snapshot
  Summary: Snapshot a VM.
  Description: Creates a snapshot of the specified VM.
  Parameters:
    - name: vmName
      in: path
      required: true
      schema: { type: string }
    - name: snapshotName
      in: query
      required: true
      schema: { type: string }
  Responses:
    200 OK:
      description: VM snapshot created.

POST /vms/{vmName}/restore
  Summary: Restore a VM from snapshot.
  Description: Restores a VM from a previously created snapshot.
  Parameters:
    - name: vmName
      in: path
      required: true
      schema: { type: string }
    - name: snapshotName
      in: query
      required: true
      schema: { type: string }
  Responses:
    200 OK:
      description: VM restored from snapshot.

```

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

### Get Sandbox Metadata and VNC Details

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Retrieves metadata for a running sandbox, including its IP address, status, and port forwarding details. This is used to find the host port for connecting to the sandbox's VNC server.

```python
# Replace this with the ip:port where `arrakis-restserver` is running.
sandbox_manager = SandboxManager('http://127.0.0.1:7000')
sb = sandbox_manager.start_sandbox('agent-sandbox')
print(sb.info())
```

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

### Build Arrakis Project

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Compiles all components of the Arrakis project, including the guest root filesystem. This command may prompt for sudo privileges.

```bash
make all
```

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

### Clone Arrakis Repository

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Clones the Arrakis project repository from GitHub and navigates into the project directory.

```bash
git clone https://github.com/abshkbh/arrakis.git
cd arrakis
```

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

### Arrakis Configuration Structure

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Illustrates the structure of the configuration file used by Arrakis services, including host and guest service settings.

```yaml
hostservices:
  restserver:
    state_dir: "/path/to/state"
    chv_bin: "/path/to/cloud-hypervisor"
    kernel: "/path/to/kernel"
    rootfs: "./out/arrakis-guestrootfs-ext4.img"
  client:
    server_host: "127.0.0.1"
    server_port: 8080
guestservices:
  codeserver:
    enabled: true
```

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

### Build Custom Guest RootFS

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Generates a custom root filesystem image for the MicroVM guest based on the provided Dockerfile.

```bash
make guestrootfs
```

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

### MCP Server Configuration for Claude Desktop

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

A sample JSON configuration file for the Arrakis MCP server, intended for use with clients like Claude Desktop App. It specifies how to run the MCP server using `uv`.

```json
{
    "mcpServers": {
      "arrakis": {
          "command": "/Users/username/.local/bin/uv",
          "args": [
            "--directory",
            "/Users/username/Documents/projects/arrakis-mcp-server",
            "run",
            "arrakis_mcp_server.py"
          ]
      }
    }
}
```

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

### Snapshot and Restore VM with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Supports creating snapshots of VMs and restoring them. Restoring currently uses the same IP as the original VM. It's recommended to stop or destroy the original VM before restoring on the same host.

```bash
./out/arrakis-client snapshot -n foo-original -o foo-snapshot
```

```bash
./out/arrakis-client destroy -n foo-original -o foo-snapshot
```

```bash
./out/arrakis-client restore -n foo-original --snapshot foo-snapshot
```

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

### Connect to Sandbox GUI via VNC Proxy

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Connects to the sandbox's GUI using a VNC client and the novnc_proxy. It uses the `host_port` obtained from the sandbox metadata to establish the connection to the VNC server running inside the sandbox.

```bash
# We see port 3000 is the host port forwarded to the VNC server running inside the sandbox.
./utils/novnc_proxy --vnc <dev-server-ip>:3000
```

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

### List All VMs with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Lists all currently managed virtual machines using the Arrakis CLI client, returning a JSON object containing an array of VM details.

```bash
./out/arrakis-client list-all
```

```json
VMs: {"vms":[{"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}]}
```

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

### Snapshot and Restore Sandbox

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Shows how to create a snapshot of a sandbox's state, modify files within the sandbox, destroy it, and then restore it from the snapshot to retrieve the original file content. This is useful for saving and reverting sandbox states.

```python
# Start a sandbox and write some data to a file.
sandbox_name = 'agent-sandbox'
sandbox = sandbox_manager.start_sandbox(sandbox_name)
sandbox.run_cmd("echo 'test data before snapshot' > /tmp/testfile")
snapshot_id = sandbox.snapshot("initial-state")
sandbox.run_cmd("echo 'test data after snapshot' > /tmp/testfile")

# Destroy the sandbox.
sandbox.destroy()

# Restore the sandbox from the snapshot and verify we have the same data at the time of the
# snapshot.
sandbox = sandbox_manager.restore(sandbox_name, snapshot_id)
result = sandbox.run_cmd("cat /tmp/testfile")
# result["output"] should be "test data before snapshot".
```

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

### Arrakis API Definitions

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

References the OpenAPI specifications for the cloud-hypervisor API and the Arrakis REST server API, used for communication between components.

```APIDOC
cloud-hypervisor API:
  Location: ./gen/cloud-hypervisor/api/arrakis-api.yaml
  Description: Defines the API for interacting with cloud-hypervisor.

REST server API:
  Location: ./gen/cloud-hypervisor/api/server-api.yaml
  Description: Defines the API for the arrakis-restserver, used by the arrakis-client.
```

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

### Check Virtualization Status

Source: https://github.com/abshkbh/arrakis/blob/main/README.md

Verifies if hardware virtualization is enabled on the host system by checking the status of the /dev/kvm device. This is a prerequisite for running Arrakis sandboxes using cloud-hypervisor on Linux.

```bash
stat /dev/kvm
```

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

### Inspect a VM with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Inspects a specific VM by its name using the Arrakis CLI client, returning its current metadata.

```bash
./out/arrakis-client list -n foo
```

```json
VM: {"ip":"10.20.1.2/24","status":"RUNNING","tapDeviceName":"tap-foo","vmName":"foo"}
```

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

### Stop a VM with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Stops a specified virtual machine using the Arrakis CLI client.

```bash
./out/arrakis-client stop -n foo
```

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

### Destroy a VM with Arrakis Client

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Destroys a specified virtual machine using the Arrakis CLI client.

```bash
./out/arrakis-client destroy -n foo
```

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

### SSH into a VM

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Connects to a running VM via SSH. The IP address is obtained from the VM's metadata, and the default credentials are 'elara' with password 'elara0000'.

```bash
# Use the IP returned. Password is "elara0000"
ssh elara@10.20.1.2
```

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

### Clean Arrakis Binaries

Source: https://github.com/abshkbh/arrakis/blob/main/docs/detailed-README.md

Removes all compiled binaries and intermediate build files generated by the 'make all' command.

```bash
make clean
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.