Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
440 lines (326 loc) · 9.57 KB

GETTING_STARTED.md

File metadata and controls

440 lines (326 loc) · 9.57 KB

Getting Started with MorphBox

Welcome to MorphBox! This guide will walk you through everything you need to get up and running with your secure AI development environment.

Table of Contents

  1. Prerequisites
  2. Installation
  3. First Launch
  4. Understanding the Interface
  5. Your First Session
  6. Next Steps

Prerequisites

Before installing MorphBox, ensure you have the following:

Required Software

1. Docker

MorphBox runs in Docker containers for isolation and security.

Check if Docker is installed:

docker --version

Install Docker if needed:

  • macOS/Windows: Download Docker Desktop
  • Linux: 
    curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

Verify Docker is running:

docker ps

If you see a table (even if empty), Docker is running correctly.

2. Node.js (for npm installation)

Check if Node.js is installed:

node --version
npm --version

Install Node.js if needed:

  • Download from nodejs.org (LTS version recommended)
  • Or use a version manager like nvm: 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

System Requirements

  • Memory: Minimum 4GB RAM (8GB recommended)
  • Storage: 10GB free disk space
  • Network: Internet connection for initial setup

Quick Prerequisites Check

Run this script to check all prerequisites:

#!/bin/bash
echo "Checking MorphBox prerequisites..."
echo ""

# Check Docker
if command -v docker &> /dev/null; then
    echo "✅ Docker installed: $(docker --version)"
    if docker ps &> /dev/null; then
        echo "✅ Docker is running"
    else
        echo "❌ Docker is not running. Please start Docker Desktop."
    fi
else
    echo "❌ Docker not found. Please install Docker."
fi

# Check Node.js
if command -v node &> /dev/null; then
    echo "✅ Node.js installed: $(node --version)"
else
    echo "❌ Node.js not found. Please install Node.js."
fi

# Check npm
if command -v npm &> /dev/null; then
    echo "✅ npm installed: $(npm --version)"
else
    echo "❌ npm not found. Please install Node.js/npm."
fi

# Check disk space
AVAILABLE=$(df -h . | awk 'NR==2 {print $4}')
echo "📊 Available disk space: $AVAILABLE"

Installation

Option 1: Global Installation (Recommended)

Install MorphBox globally to use it from anywhere:

npm install -g morphbox

Verify installation:

morphbox --version

Troubleshooting npm global installation:

If you get "command not found" after installation:

  1. Find your npm global bin directory:

    npm config get prefix

  2. Add it to your PATH:

    # For bash (add to ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# For zsh (add to ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc

Option 2: Use Without Installation (npx)

If you prefer not to install globally:

npx morphbox

This downloads and runs MorphBox on demand.

Option 3: Install from Source

For developers or contributors:

# Clone the repository
git clone https://github.com/instant-unicorn/morphbox.git
cd morphbox/web

# Install dependencies
npm install

# Link globally (optional)
npm link

# Run directly
npm run start

First Launch

Starting MorphBox

  1. Navigate to your project directory:

    cd ~/my-project

  2. Start MorphBox:

    morphbox

  3. What happens on first launch:

    • Docker image download (one-time, ~500MB)
    • Container creation
    • Service initialization
    • Web interface starts

    First launch takes 2-3 minutes. Subsequent launches take <30 seconds.

First Launch Output

You'll see output like this:

[INFO] Checking Docker container...
[INFO] Creating MorphBox VM container with workspace: /home/user/my-project
[INFO] Building Docker image... (this may take a few minutes on first run)
[INFO] Container created successfully
[INFO] Starting web interface...
[INFO] 
[INFO] ✨ MorphBox is ready!
[INFO] 
[INFO] 🌐 Web Interface: http://localhost:3000
[INFO] 📁 Workspace: /home/user/my-project mounted as /workspace
[INFO] 
[INFO] Press Ctrl+C to stop MorphBox

Understanding the Interface

Web Interface (Default)

Open your browser to http://localhost:3000. You'll see:

  1. Terminal Panel (Left)

    • Full bash terminal
    • Access to /workspace (your mounted directory)
    • All development tools available

  2. Claude Panel (Right)

    • AI assistant interface
    • Code-aware context
    • Markdown rendering for responses

  3. Toolbar (Top)

    • New Terminal button
    • Layout options
    • Settings

Terminal Mode

For a pure terminal experience:

morphbox --terminal

This launches Claude directly in your terminal - perfect for users who prefer CLI.

Key Concepts

  • Workspace: Your current directory is mounted as /workspace in the container
  • Isolation: The container cannot access files outside the mounted workspace
  • Persistence: Claude's configuration and your work persist between sessions
  • Security: Network access is restricted to allowed domains only

Your First Session

Let's create a simple project with Claude's help:

Example 1: Create a Python Script

  1. Start MorphBox in a new directory:

    mkdir my-first-morphbox
cd my-first-morphbox
morphbox

  2. In the Claude panel, type:

    Help me create a Python script that fetches weather data from an API
and displays it nicely formatted

  3. Claude will:

    • Write the Python code
    • Explain how it works
    • Suggest how to run it

  4. In the terminal panel:

    # See the created file
ls -la

# Run the script
python weather.py

Example 2: Web Development

  1. Ask Claude:

    Create a simple responsive landing page with HTML, CSS, and JavaScript
that has a dark mode toggle

  2. Claude will create:

    • index.html
    • styles.css
    • script.js

  3. Preview your work:

    # In the terminal panel
python -m http.server 8000

    Then open http://localhost:8000 in a new browser tab.

Example 3: Learning Mode

Ask Claude to teach you:

Explain Docker to me with examples, then help me create my first Dockerfile

Claude will:

  • Provide conceptual explanation
  • Show practical examples
  • Guide you through creating a Dockerfile
  • Help you build and run it

Common Commands

MorphBox Commands

morphbox              # Start with web UI
morphbox --terminal   # Terminal mode
morphbox --vpn        # Bind to VPN interface
morphbox --auth       # Enable authentication
morphbox --help       # Show all options

Inside the Container

# Navigation
cd /workspace         # Your mounted directory
ls -la               # List files

# Development
node app.js          # Run Node.js apps
python script.py     # Run Python scripts
npm install          # Install packages

# Claude specific
claude --help        # Claude CLI options

Configuration

Basic Configuration

Create .morphbox.env in your project:

# Change the web interface port
MORPHBOX_PORT=8080

# Enable authentication
MORPHBOX_AUTH_ENABLED=true
MORPHBOX_AUTH_USERNAME=myusername

Advanced Configuration

See Configuration Reference for all options.

Troubleshooting First-Time Issues

Issue: "Docker daemon not running"

Solution:

# macOS/Windows: Start Docker Desktop application
# Linux:
sudo systemctl start docker

Issue: "Port 3000 already in use"

Solution:

# Use a different port
MORPHBOX_PORT=8080 morphbox

Issue: "Permission denied"

Solution:

# Linux: Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Issue: "Container fails to start"

Solution:

# Remove any existing container
docker rm -f morphbox-vm

# Try again
morphbox

Next Steps

Now that you have MorphBox running:

  1. Read the Tutorials - docs/TUTORIALS.md

    • Build a full-stack application
    • Learn test-driven development
    • Create API endpoints

  2. Explore Use Cases - docs/USE_CASES.md

    • Code reviews
    • Learning new languages
    • Debugging assistance

  3. Customize Your Environment - docs/CONFIGURATION.md

    • Add your favorite tools
    • Configure shortcuts
    • Set up team access

  4. Join the Community

Getting Help

Tips for Success

  1. Start Simple: Begin with small tasks to understand the workflow
  2. Be Specific: Give Claude clear, detailed instructions
  3. Iterate: Refine your requests based on Claude's responses
  4. Explore: Try different types of projects and languages
  5. Save Your Work: Remember to commit changes to git

Ready to build something amazing? You now have a powerful AI assistant in a secure sandbox. Happy coding! 🚀