Phantom Fragment - Next-Generation Container Alternative for LLM Agents

Phantom Fragment is the optimal next-generation architecture for LLM-native sandboxing, achieving <80ms startups, <10MB RSS memory usage, and 4-6× the I/O performance of Docker.

With newly integrated WebAssembly and Landlock security, Phantom Fragment provides a revolutionary, performance-by-design sandbox environment engineered specifically for LLM agents and AI-assisted development. It delivers these results through kernel-native optimization and zero-overhead security.

This document provides a comprehensive overview of Phantom Fragment, from basic installation and usage to advanced topics like performance tuning, security, and testing.

🚀 Performance Highlights

Phantom Fragment is designed from the ground up to be significantly faster and lighter than traditional containerization solutions like Docker. This is achieved through a combination of kernel-native features and an architecture optimized for the common workflows of AI agents.

Metric	Phantom Fragment	Docker	Improvement
Cold Start	<80ms	387ms	>4.8× faster
Warm Start	23ms	156ms	6.8× faster
Memory/Container	<10MB	67MB	>6.7× lighter
I/O Throughput	>2.5GB/s	890MB/s	4-6× faster
Binary Size	47MB	2.3GB daemon	49× smaller
Security Overhead	<5ms	N/A	N/A

Benchmarked on Linux 6.5, Intel i7-12700K, 32GB RAM, NVMe SSD

📦 Installation

Quick Install (Recommended)

# Download the latest release for Linux
wget https://github.com/phantom-fragment/releases/latest/phantom-fragment-linux.tar.gz

# Extract the archive
tar xzf phantom-fragment-linux.tar.gz

# Navigate into the project directory
cd phantom-fragment

Important: Directory Usage

ALL COMMANDS MUST BE RUN FROM THE PROJECT DIRECTORY.

Phantom Fragment is designed with an optimized directory structure. To ensure all components work correctly, always run commands from within the phantom-fragment directory.

# ❌ WRONG (running from a parent directory):
PS C:\path\to\parent> phantom-fragment\bin\phantom.exe --help
# This will likely fail to find necessary resources.

# ✅ CORRECT (navigate to the project directory first):
PS C:\path\to\parent> cd phantom-fragment
PS C:\path\to\parent\phantom-fragment> .\bin\phantom.exe --help
# This will work as expected.

🚀 Quick Start

This example demonstrates how to run a simple Python script inside a secure Phantom Fragment sandbox.

# Navigate to the project directory
cd phantom-fragment

# Execute a one-line Python script and measure the startup time
time ./bin/phantom run --profile python-dev python -c "import sys; print(f'Python {sys.version} in {sys.platform} fragment')"

# For comparison, run the same command with Docker
time docker run --rm python:3.11-alpine python -c "import sys; print(f'Python {sys.version} in {sys.platform} container')"

You should observe that Phantom Fragment completes the task in a fraction of the time it takes Docker, typically 4-6 times faster.

💻 Usage

For Human Developers (CLI)

The phantom CLI is your primary tool for interacting with fragments. It's designed to be fast, intuitive, and powerful.

# Run a command in a sandboxed environment with a specific profile
# The 'python-dev' profile provides a secure environment for Python development
./bin/phantom run --profile python-dev python your_script.py

# Run a WebAssembly module
./bin/phantom run --mode wasm --profile wasm-runtime your_module.wasm

# Create a persistent workspace for a project
# This creates a 'zygote' (a pre-warmed instance) for ultra-fast access
./bin/phantom create --name my-ai-project --profile go-dev --mode direct

# List all available security and performance profiles
./bin/phantom profile list --benchmark

# Monitor the real-time performance of a running fragment
./bin/phantom monitor my-ai-project --metrics

# Properly shut down and clean up a fragment and its resources
./bin/phantom destroy my-ai-project

For LLM Agents (MCP Integration)

Phantom Fragment can be integrated with LLM agents like Claude, GPT, or Gemini via the Model Context Protocol (MCP), providing them with a secure, high-performance execution environment.

1. Start the MCP Server

The MCP server acts as a bridge between the LLM agent and Phantom Fragment.

# Navigate to the project directory
cd phantom-fragment

# Start the MCP server in stdio mode with pre-warmed zygotes for the fastest response
# This is ideal for desktop agents or tools that can communicate over stdin/stdout
./bin/phantom-mcp --transport stdio --mode zygote --profiles python,node,go

# Alternatively, start an HTTP server for web-based LLMs or services
# This uses io_uring for high-performance networking on Linux
./bin/phantom-mcp --transport http --port 8080 --io-mode uring

2. Configure Your LLM Agent

You'll need to configure your agent to use the MCP server. Here is an example for a hypothetical desktop agent:

{
  "mcpServers": {
    "phantom-fragment": {
      "command": "C:\\path\\to\\phantom-fragment\\bin\\phantom-mcp.exe",
      "args": ["--transport", "stdio", "--mode", "zygote", "--profiles", "python,node,go"],
      "env": {
        "PHANTOM_PERFORMANCE_MODE": "maximum",
        "PHANTOM_ZYGOTE_POOL_SIZE": "3"
      }
    }
  }
}

Once configured, your LLM agent can execute code, manage files, and perform other tasks within the secure confines of Phantom Fragment, with near-native performance.

🧪 Testing

This project includes several scripts to test functionality, performance, and integrations.

Performance & Integration Tests

These scripts run a comprehensive suite of tests to benchmark performance and validate key features.

• test-phantom-performance.sh (for Linux/macOS)
• test-phantom-performance.ps1 (for Windows)

Usage:

# On Linux or macOS
./test-phantom-performance.sh

# On Windows (you may need to adjust your execution policy)
powershell -ExecutionPolicy Bypass -File ./test-phantom-performance.ps1

These tests will benchmark core operations like startup time, I/O throughput, and memory usage, and compare them against Docker if it is installed.

MCP Protocol Tests

This script specifically tests the Model Context Protocol (MCP) server to ensure it's functioning correctly and measures its responsiveness.

• test-mcp-basic.sh

Usage:

# This script tests the basic functionality of the MCP server
./test-mcp-basic.sh

Fragment-Specific Benchmarks

This script allows you to run performance tests on specific fragments to measure their individual performance.

• test-fragments-benchmark.sh

Usage:

# Run benchmarks on all fragments with 100 iterations each
./test-fragments-benchmark.sh --fragment all --iterations 100

# Run a benchmark specifically on the 'zygote' fragment
./test-fragments-benchmark.sh --fragment zygote

🛠️ How it Works

Phantom Fragment avoids the overhead of traditional virtualization and containerization by using a set of specialized, high-performance components called "fragments."

Fragment Architecture

Instead of a monolithic daemon, Phantom Fragment is composed of independent yet cooperative fragments, each optimized for a specific task.

graph TB
    subgraph "Performance Fragments"
        ZY[Zygote Spawner (<80ms)]
        IO[I/O Fast Path (io_uring, Atomic Writes)]
        MEM[Memory Discipline (Zero churn)]
    end

    subgraph "Security Fragments"
        SEC[Line Rate Security (BPF-LSM, Landlock)]
        NET[Network Minimalist (eBPF/XDP, QUIC)]
        POL[Policy DSL (AOT compiled)]
    end

    subgraph "Orchestration Fragments"
        ORCH[Graph Orchestrator (PSI/NUMA, ML)]
        MODE[Adaptive Modes (Direct/Sandbox/Hardened/Wasm)]
        FRAG[Fragment Store (CAS, deltas)]
    end

    ZY --> ORCH
    IO --> ORCH
    MEM --> ORCH
    SEC --> POL
    NET --> POL
    POL --> MODE
    ORCH --> MODE
    MODE --> FRAG

Loading

Key Advantages over Docker:

• Zygote Spawning: We use pre-warmed process templates (clone3()) instead of starting a new container from scratch every time. This is a primary reason for our sub-100ms startup times.
• WebAssembly Support: Run sandboxed Wasm modules with near-native performance, expanding the range of supported portable applications.
• Direct Rootfs: We use a simple, direct filesystem layout, avoiding the performance penalty of Docker's layered filesystem (like overlay2).
• Kernel-Native Integration: We leverage advanced Linux kernel features like BPF, seccomp, io_uring, and Landlock directly for maximum performance and security.
• Self-Contained Binary: The entire system is distributed as a single, ~50MB binary with an embedded Alpine Linux rootfs, making it portable and easy to deploy.

🔒 Security-by-Design

Security is not an afterthought in Phantom Fragment; it is a core design principle with zero performance overhead.

Isolation Technologies

We use a multi-layered security approach to isolate sandboxed environments:

• User Namespaces: Ensures that processes inside the sandbox run as unprivileged users on the host system.
• Landlock: A modern, unprivileged access-control system that allows processes to sandbox themselves. This is a key part of our zero-overhead security model.
• Seccomp Profiles: We use strict system call filtering to restrict what a sandboxed process can do. Profiles are tailored for each language (e.g., Python, Node.js) to minimize the attack surface.
• Capabilities Control: We drop all unnecessary Linux capabilities, following the principle of least privilege.
• Read-only Filesystem: The base rootfs is immutable, preventing any modification of the core environment.
• Network Isolation: Network access is disabled by default and can be enabled with strict eBPF/XDP-based rules.
• Resource Limits: CPU, memory, and disk usage are constrained using cgroups.

Security Profiles

Phantom Fragment comes with pre-configured security profiles for common use cases. You can see the full list by running ./bin/phantom profile list.

Profile	Language	Network	Filesystem	Use Case
python-dev	Python	Limited	Restricted	Secure Python development
node-dev	Node.js	Limited	Restricted	Secure JavaScript/Node development
wasm-runtime	WebAssembly	Disabled	Read-only	For running untrusted Wasm modules
strict	Any	Disabled	Read-only	For maximum security applications

🎯 Use Cases

• AI Agent Development: Provide a safe and fast execution environment for code generated by LLMs.
• Educational Environments: Allow students to run code in a secure, isolated sandbox.
• CI/CD Integration: Run build and test jobs in clean, fast, and disposable environments.
• Malware Analysis: Safely analyze suspicious code without risking system integrity.

🔧 Building from Source

If you want to build Phantom Fragment from source, you will need Go 1.21+ and Git.

# Navigate to the project directory
cd phantom-fragment

# Build all components with performance optimizations
# The -ldflags="-s -w" strips debug information, making the binary smaller
# The -tags="netgo,osusergo,static" creates a statically linked binary
go build -ldflags="-s -w" -tags="netgo,osusergo,static" -o bin/phantom ./cmd/phantom
go build -ldflags="-s -w" -tags="netgo,osusergo,static" -o bin/phantom-mcp ./cmd/phantom-mcp
go build -ldflags="-s -w" -tags="netgo,osusergo,static" -o bin/phantom-supervisor ./cmd/phantom-supervisor

⚙️ Configuration

You can customize Phantom Fragment's behavior through a config.yaml file or environment variables.

Policy DSL Example

Here is an example of how to define a custom profile using the new Policy DSL in your config.yaml:

# Example Policy DSL
profile: python-ai-turbo
mode: sandbox
runtime: auto

security:
  level: medium
  seccomp:
    default: deny
    allow: [read, write, openat, close, mmap, exit_group]
  landlock:
    enabled: true
    paths:
      - path: /tmp
        access: read-write
      - path: /usr/lib/python3*
        access: read-only

performance:
  zygote: true
  io_mode: uring
  memory_allocator: jemalloc

resources:
  memory: 512MB
  cpu: 1.0
  pids: 256

network:
  mode: loopback-only

Environment Variables

# Set the path to your configuration file
export PHANTOM_CONFIG_PATH=/path/to/your/config.yaml

# Set the default security profile to use
export PHANTOM_DEFAULT_PROFILE=my-custom-profile

# Enable verbose debug logging
export PHANTOM_DEBUG=true

🔍 Troubleshooting

"Command Not Found" Errors

• Error Message: bash: ./bin/phantom: No such file or directory or The term '.\bin\phantom.exe' is not recognized...
• Cause: You are likely in the wrong directory.
• Solution: Make sure you have navigated into the phantom-fragment project directory before running any commands.

Go Module Errors

• Error Message: go: go.mod file not found in current directory
• Cause: You are trying to run a go build command from outside the project directory.
• Solution: Navigate to the phantom-fragment directory where the go.mod file is located.

Permission Errors on Windows

• Error Message: ...cannot be loaded because running scripts is disabled on this system.
• Cause: PowerShell's execution policy is preventing the test scripts from running.
• Solution: You can bypass the policy for a single command by running PowerShell as an administrator or using the -ExecutionPolicy Bypass flag:

  powershell -ExecutionPolicy Bypass -File .\test-phantom-performance.ps1

Getting Help from the CLI

If you need more information about a command, you can use the --help flag.

# Get help for the main command
./bin/phantom --help

# Get help for a specific subcommand, like 'run'
./bin/phantom run --help

# Get help for the MCP server
./bin/phantom-mcp --help