Cuttlefish

Cuttlefish is Google's virtual Android device reference implementation, optimized and deployed at scale on the Null Autos platform.

What is Cuttlefish?

Cuttlefish is a configurable virtual Android device that can run on Linux x86 servers. Null Autos has optimized Cuttlefish for cloud deployment, providing:

• Hardware Acceleration: Full GPU and hardware acceleration support
• High Performance: Near-native Android performance
• Flexibility: Customizable device configurations
• Cloud Native: Optimized for containerized environments

Features

Android Compatibility

• Latest Android Versions: Support for Android 11-14+
• AOSP Builds: Use stock Android or custom builds
• Android Automotive: Specialized automotive OS support
• Device Profiles: Phone, tablet, automotive, TV, and custom

Hardware Emulation

• Graphics: Accelerated graphics with GPU passthrough
• Sensors: Accelerometer, gyroscope, GPS, and custom sensors
• Connectivity: WiFi, Bluetooth, cellular emulation
• Audio: Audio playback and recording
• Camera: Virtual camera support

Development Features

• ADB Support: Full Android Debug Bridge access
• Fastboot: Flash custom images and partitions
• Serial Console: Direct console access
• Logcat Streaming: Real-time log access
• Screen Recording: Capture device screen

Cuttlefish vs Traditional Emulators

Feature	Cuttlefish	Traditional Emulator
Performance	Near-native	50-70% native
Boot Time	15-30s	60-120s
Hardware Acceleration	Full KVM	Limited
Customization	Highly flexible	Limited
Cloud Deployment	Optimized	Challenging
Resource Efficiency	High	Medium

Device Profiles

Automotive Profile

Optimized for Android Automotive OS:

{
  "profile": "automotive",
  "androidVersion": "14.0",
  "display": {
    "width": 1920,
    "height": 1080,
    "dpi": 160
  },
  "hardware": {
    "cpus": 4,
    "memory": 4096,
    "gpu": true
  },
  "features": [
    "vehicle_hal",
    "can_bus",
    "hvac",
    "radio"
  ]
}

Phone Profile

Standard Android phone configuration:

{
  "profile": "phone",
  "androidVersion": "14.0",
  "display": {
    "width": 1080,
    "height": 2400,
    "dpi": 420
  },
  "hardware": {
    "cpus": 2,
    "memory": 2048,
    "gpu": true
  }
}

Custom Profile

Create your own device profiles:

{
  "profile": "custom",
  "androidVersion": "13.0",
  "display": {
    "width": 800,
    "height": 480,
    "dpi": 160
  },
  "hardware": {
    "cpus": 2,
    "memory": 1024,
    "gpu": false
  }
}

Performance Optimization

Resource Allocation

Null Autos optimizes Cuttlefish for cloud deployment:

• CPU Pinning: Dedicated CPU cores for low latency
• NUMA Awareness: Optimized memory access
• GPU Scheduling: Efficient GPU resource sharing
• Network Optimization: Low-latency networking

Scaling

• Horizontal Scaling: Run hundreds of devices per node
• Vertical Scaling: Adjust resources per device
• Auto-scaling: Dynamic resource allocation
• Load Balancing: Distributed device placement

Use Cases

Automotive Development

Perfect for Android Automotive OS development:

• IVI Testing: In-vehicle infotainment systems
• Instrument Cluster: Digital gauge clusters
• ADAS Integration: Advanced driver assistance
• Vehicle Connectivity: Test vehicle APIs and services

Mobile App Testing

Comprehensive mobile testing capabilities:

• UI Automation: Automated UI testing
• Performance Testing: Profile app performance
• Compatibility Testing: Test across Android versions
• Integration Testing: Test with backend services

CI/CD Integration

Seamless integration with development workflows:

# GitHub Actions example
- name: Run Tests on Cuttlefish
  uses: null-autos/cuttlefish-action@v1
  with:
    android-version: '14.0'
    profile: 'automotive'
    test-command: 'npm run test:e2e'

Technical Details

System Requirements

Per Cuttlefish instance:

• CPU: 2-4 vCPUs (x86_64 with KVM)
• Memory: 2-4 GB RAM
• Storage: 10-20 GB SSD
• GPU: Optional, recommended for graphics-heavy workloads

Networking

• TAP Networking: Isolated network per device
• Port Forwarding: Expose device ports
• VPN Support: Private connectivity
• Bandwidth: Up to 1 Gbps per device

Storage

• System Image: 4-8 GB
• User Data: Configurable, persistent across reboots
• Snapshots: Fast state snapshots
• Shared Storage: Optional shared volumes

API Integration

Creating Cuttlefish Devices

import { CtrlClient } from '@null-autos/ctrl-sdk';

const ctrl = new CtrlClient({ apiKey: 'your-api-key' });

const device = await ctrl.devices.create({
  type: 'cuttlefish',
  androidVersion: '14.0',
  profile: 'automotive',
  hardware: {
    cpus: 4,
    memory: 4096,
    gpu: true,
  },
});

console.log(`Device created: ${device.id}`);
console.log(`ADB: adb connect ${device.adbEndpoint}`);

Interacting with Devices

// Execute ADB commands
await device.adb.shell('input tap 500 500');

// Install an APK
await device.adb.install('/path/to/app.apk');

// Get device logs
const logs = await device.logs.stream();
logs.on('data', (line) => console.log(line));

// Take a screenshot
const screenshot = await device.screen.capture();

Custom Android Builds

Using Custom System Images

const device = await ctrl.devices.create({
  type: 'cuttlefish',
  customImage: {
    url: 'https://builds.example.com/aosp-14-automotive.img',
    checksum: 'sha256:abc123...',
  },
});

Build Requirements

Custom images must:

• Be compatible with Cuttlefish
• Include necessary kernel modules
• Support KVM hardware acceleration
• Follow Android CDD (Compatibility Definition Document)

Monitoring & Diagnostics

Health Checks

• Boot Status: Monitor device boot progress
• System Health: CPU, memory, disk usage
• Network Status: Connectivity checks
• App Monitoring: Installed app status

Logs & Debugging

• Logcat: Real-time Android logs
• Kernel Logs: Low-level kernel messages
• Crash Reports: Automatic crash detection
• Performance Metrics: FPS, memory, CPU usage

Best Practices

Resource Management

1. Right-size devices: Use appropriate CPU/memory for workload
2. Clean up unused devices: Delete when no longer needed
3. Use snapshots: Save device states for faster testing
4. Monitor usage: Track resource consumption

Performance

1. Enable GPU: For graphics-intensive applications
2. Use SSD storage: Faster boot and I/O
3. Optimize images: Minimize system image size
4. Network tuning: Adjust network settings for latency

Security

1. Isolated networks: Use per-device network isolation
2. Rotate credentials: Regular API key rotation
3. Audit logs: Monitor device access
4. Update images: Keep Android builds current

Troubleshooting

Common Issues

Device won't boot

• Check system image compatibility
• Verify resource allocation (CPU, memory)
• Review boot logs for errors

Slow performance

• Enable GPU acceleration
• Increase CPU/memory allocation
• Check host node load

Network connectivity

• Verify network configuration
• Check firewall rules
• Test with ping/curl

ADB connection issues

• Verify ADB endpoint is reachable
• Check authentication credentials
• Restart ADB server

Resources

• Cuttlefish Official Docs
• Android Automotive Guide
• AOSP Build Instructions
• Null Autos API Reference

Support

For Cuttlefish-specific support:

• Email: cuttlefish-support@null.autos
• Documentation: docs.null.autos/cuttlefish
• Community: community.null.autos