​
Overview

The Bytebot Desktop Environment is a fully functional Linux desktop running inside a Docker container. It’s the workspace where your AI agent performs tasks - clicking, typing, browsing, and working with applications just like a human would at a physical computer.

​
Why a Containerized Desktop?

​
Complete Isolation

  • No Risk to Host: All actions happen inside the container
  • Sandboxed Environment: Desktop can’t access your host system
  • Easy Reset: Destroy and recreate in seconds
  • Multiple Instances: Run several agents simultaneously

​
Consistency Everywhere

  • Platform Independent: Same environment on Mac, Windows, or Linux
  • Reproducible: Identical setup every time
  • Version Control: Pin specific versions for stability
  • No Dependencies: Everything included in the container

​
Built for Automation

  • Predictable UI: Consistent element positioning
  • Clean Environment: No popups or distractions
  • Automation-Ready: Optimized for programmatic control
  • Fast Startup: Desktop ready in seconds

​
Technical Stack

​
Base System

  • Ubuntu 22.04 LTS: Stable, well-supported Linux distribution
  • XFCE4 Desktop: Lightweight, responsive desktop environment
  • X11 Display Server: Standard Linux graphics system
  • supervisord: Service management

​
Pre-installed Software

Web Browsers

  • Firefox ESR (Extended Support Release)
  • Pre-configured for automation
  • Ad blocker extensions

Office Tools

  • Text editors (nano, vim, gedit)
  • PDF viewer
  • File managers

Communication

  • Thunderbird email client
  • Chat applications
  • Terminal emulators

Development

  • Git version control
  • Python 3 environment
  • Node.js runtime
  • Common dev tools

​
Core Services

  1. bytebotd Daemon

    • Runs on port 9990
    • Handles all automation requests
    • Built on nutjs framework
    • Provides REST API

  2. noVNC Web Client

    • Browser-based desktop access
    • No client installation needed
    • WebSocket proxy included

  3. Supervisor

    • Process management
    • Service monitoring
    • Automatic restarts
    • Log management

​
Desktop Features

​
Display Configuration

# Default resolution
1920x1080 @ 24-bit color

# Configurable via environment
DISPLAY_WIDTH=1920
DISPLAY_HEIGHT=1080
DISPLAY_DEPTH=24

​
User Environment

  • Username: user
  • Home Directory: /home/user
  • Sudo Access: Yes (passwordless)
  • Desktop Session: Auto-login enabled

​
File System

/home/user/
├── Desktop/          # Desktop shortcuts
├── Documents/        # User documents
├── Downloads/        # Browser downloads
├── .config/          # Application configs
└── .local/           # User data

​
Accessing the Desktop

Navigate to http://localhost:9990/vnc for instant access:

  • No software installation required
  • Works on any device with a browser
  • Supports touch devices
  • Clipboard sharing

​
MCP Control

The core container also exposes an MCP endpoint. Connect your MCP client to http://localhost:9990/mcp to invoke these tools over SSE.

{
  "mcpServers": {
    "bytebot": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:9990/mcp",
        "--transport",
        "http-first"
      ]
    }
  }
}

​
Direct API Control

Most efficient for automation:

# Take a screenshot
curl -X POST http://localhost:9990/api/computer \
  -H "Content-Type: application/json" \
  -d '{"action": "screenshot"}'

# Move mouse
curl -X POST http://localhost:9990/api/computer \
  -H "Content-Type: application/json" \
  -d '{"action": "move_mouse", "coordinate": {"x": 500, "y": 300}}'

​
Customization

​
Adding Software

Create a custom Dockerfile:

FROM ghcr.io/bytebot-ai/bytebot-desktop:edge

# Install additional packages
RUN apt-get update && apt-get install -y \
    slack-desktop \
    zoom \
    your-custom-app

# Copy configuration files
COPY configs/ /home/user/.config/

​
Environment Variables

Configure behavior via environment:

# docker-compose.yml
environment:
  - DISPLAY_WIDTH=1920
  - DISPLAY_HEIGHT=1080

​
Performance Optimization

​
Resource Allocation

# Recommended settings
deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G
    reservations:
      cpus: '1'
      memory: 2G

​
Security Hardening

Default configuration prioritizes ease of use. For production, apply these security measures:

​
Essential Security Steps

  1. Change Default Passwords

    # Set user password
passwd bytebot

  2. Restrict Network Access

    # Only expose to localhost
ports:
  - "127.0.0.1:9990:9990"

  3. Remove Sudo Access

    # In custom Dockerfile
RUN deluser bytebot sudo

  4. Enable Authentication

    # Add nginx proxy with auth
location / {
  auth_basic "Restricted";
  auth_basic_user_file /etc/nginx/.htpasswd;
  proxy_pass http://bytebot:9990;
}

​
Troubleshooting

​
Best Practices

  1. Regular Updates: Keep the base image updated for security patches
  2. Persistent Storage: Mount volumes for important data
  3. Backup Configurations: Save customizations outside the container
  4. Monitor Resources: Track CPU/memory usage
  5. Clean Temporary Files: Periodic cleanup for performance

​
Next Steps

Quick Start

Deploy your first agent

API Reference

Control the desktop programmatically

Agent System

Add AI capabilities

Security Guide

Harden for production