Configuration

Configure Phantom with config files, hooks, templates, and environment variables.

Phantom can be configured via YAML config files, environment variables, and command-line flags. This page covers all configuration options.

Config File

The main configuration file is located at ~/.phantom/config.yaml. You can create it with:

phantom init

Default Configuration

# Phantom Configuration
# Generated by: phantom init

# Base directory for all Phantom data
data_dir: ~/.phantom

# Overlay settings
overlays:
  # Directory where overlays are stored
  dir: ~/.phantom/overlays

  # Directory where overlays are mounted
  mount_dir: ~/.phantom/mnt

  # Default timeout for agent runs
  default_timeout: 30m

  # Maximum number of parallel overlays
  max_parallel: 5

# Git settings
git:
  # Auto-commit after agent finishes
  auto_commit: true

  # Default branch prefix
  branch_prefix: phantom/

  # Push on apply
  push_on_apply: false

# Hooks (global)
hooks:
  on_success: []
  on_failure: []
  on_complete: []

# Logging
logging:
  # Log level: debug, info, warn, error
  level: info

  # Log file location
  file: ~/.phantom/phantom.log

# Agent defaults
agents:
  # Default agent command
  default: claude --print

  # Timeout for individual agents
  timeout: 30m

# Projects mapped to absolute paths
projects:
  myapp: "/Users/user/Projects/myapp"

Configuration Locations

Phantom looks for configuration in the following order (later files override earlier):

/etc/phantom/config.yaml - System-wide config
~/.phantom/config.yaml - User config (default)
./.phantom.yaml - Project-specific config
--config flag - Explicitly specified config

Environment Variables

All configuration options can be set via environment variables with the PHANTOM_ prefix:

# Set data directory
export PHANTOM_DATA_DIR=~/.phantom

# Set default timeout
export PHANTOM_OVERLAYS_DEFAULT_TIMEOUT=1h

# Set log level
export PHANTOM_LOGGING_LEVEL=debug

# Disable auto-commit
export PHANTOM_GIT_AUTO_COMMIT=false

Environment Variable Reference

Environment Variable	Config Path	Default
`PHANTOM_DATA_DIR`	`data_dir`	`~/.phantom`
`PHANTOM_OVERLAYS_DIR`	`overlays.dir`	`~/.phantom/overlays`
`PHANTOM_OVERLAYS_MOUNT_DIR`	`overlays.mount_dir`	`~/.phantom/mnt`
`PHANTOM_OVERLAYS_DEFAULT_TIMEOUT`	`overlays.default_timeout`	`30m`
`PHANTOM_OVERLAYS_MAX_PARALLEL`	`overlays.max_parallel`	`5`
`PHANTOM_GIT_AUTO_COMMIT`	`git.auto_commit`	`true`
`PHANTOM_GIT_BRANCH_PREFIX`	`git.branch_prefix`	`phantom/`
`PHANTOM_GIT_PUSH_ON_APPLY`	`git.push_on_apply`	`false`
`PHANTOM_LOGGING_LEVEL`	`logging.level`	`info`
`PHANTOM_LOGGING_FILE`	`logging.file`	`~/.phantom/phantom.log`
`PHANTOM_AGENTS_DEFAULT`	`agents.default`	`claude --print`
`PHANTOM_AGENTS_TIMEOUT`	`agents.timeout`	`30m`

Hooks

Hooks are commands that run at specific points in the overlay lifecycle.

Hook Types

Type	When it runs
`on_success`	After agent completes successfully
`on_failure`	After agent fails
`on_complete`	After agent finishes (success or failure)

Configuring Hooks

In config file:

hooks:
  on_success:
    - command: npm test
      timeout: 5m
    - command: npm run lint
      timeout: 2m
  on_failure:
    - command: 'notify-send "Phantom" "Agent failed"'
  on_complete:
    - command: ./scripts/cleanup.sh

Via CLI:

# Add a hook
phantom hook add my-overlay --type on_success --command "npm test"

# List hooks
phantom hook list my-overlay

# Remove a hook
phantom hook remove my-overlay --index 0

Hook Context

Hooks receive environment variables with context about the overlay:

Variable	Description
`PHANTOM_OVERLAY_NAME`	Name of the overlay
`PHANTOM_OVERLAY_PATH`	Path to overlay mount point
`PHANTOM_BASE_PATH`	Path to base directory
`PHANTOM_AGENT_COMMAND`	The agent command that ran
`PHANTOM_AGENT_EXIT_CODE`	Exit code of the agent
`PHANTOM_TASK`	Task description

Hook Examples

Run tests on success:

hooks:
  on_success:
    - command: npm test
      timeout: 10m

Notify on failure:

hooks:
  on_failure:
    - command: 'curl -X POST $SLACK_WEBHOOK -d "{\"text\": \"Phantom task failed: $PHANTOM_OVERLAY_NAME\"}"'

Cleanup temp files:

hooks:
  on_complete:
    - command: rm -rf /tmp/phantom-*

Templates

Templates are reusable configurations for common workflows.

Creating Templates

# Generate an agents template
phantom template agents > agents.yaml

# Generate a chain template
phantom template chain > chain.yaml

# Generate a hooks template
phantom template hooks > hooks.yaml

Agents Template

# agents.yaml - Configuration for parallel agents
agents:
  - name: feature
    command: claude --print
    task: "Implement the feature"
    timeout: 30m
    hooks:
      on_success:
        - npm test

  - name: tests
    command: aider
    task: "Add tests for the feature"
    timeout: 20m

  - name: docs
    command: gemini
    task: "Update documentation"
    timeout: 15m

Chain Template

# chain.yaml - Configuration for sequential chain
steps:
  - name: implement
    command: claude --print
    task: "Implement the feature"

  - name: test
    command: aider
    task: "Add comprehensive tests"

  - name: review
    command: claude --print
    task: "Review code for issues and improvements"

Project Configuration

Create a .phantom.yaml file in your project root for project-specific settings:

# .phantom.yaml - Project-specific Phantom configuration

# Project-specific hooks
hooks:
  on_success:
    - command: npm run test:unit
    - command: npm run lint

# Default agents for this project
agents:
  default: claude --print --model claude-3-opus

# Project-specific timeouts
overlays:
  default_timeout: 45m

# Exclude patterns (not monitored by watch)
exclude:
  - node_modules/**
  - dist/**
  - .git/**

Advanced Configuration

Custom Mount Options

overlays:
  # Linux overlayfs options
  overlayfs_options:
    - index=off
    - metacopy=on

  # FUSE options (macOS/fuse-overlayfs)
  fuse_options:
    - allow_other
    - uid=1000
    - gid=1000

Resource Limits

# Resource limits for agents
agents:
  # Maximum memory (0 = unlimited)
  max_memory: 2GB

  # Maximum CPU percentage
  max_cpu: 80

  # Maximum file descriptors
  max_fds: 1024

Security Settings

security:
  # Allowed agent commands (empty = all allowed)
  allowed_agents:
    - claude
    - aider
    - gemini

  # Sandbox agent processes
  sandbox: true

  # Network access for agents
  network: true

Config Commands

# View current configuration
phantom config

# Get a specific value
phantom config get overlays.default_timeout

# Set a value
phantom config set git.auto_commit false

# Open config in editor
phantom config edit

# Show config file path
phantom config path

Path Protection (.phantomignore)

You can protect specific files and directories in your repository from being modified by Phantom overlays using a .phantomignore file. This is useful for preventing agents from accidentally deleting crucial configuration files, credentials, or sensitive data.

How it works

When you run phantom apply, Phantom checks for a .phantomignore file in the root of your base directory. If it exists, it validates every change in the overlay against the rules defined in the file. If any modification (add, update, or delete) matches a rule, the apply operation is rejected.

Syntax

The .phantomignore file uses a syntax similar to .gitignore:

Lines starting with # are comments.
Empty lines are ignored.
Patterns without a slash match any file or directory with that name anywhere in the tree.
Patterns starting with a / are anchored to the repository root.
Patterns ending with a / match directories and all their contents.
* can be used as a wildcard (matching within a single directory).

Example

# Protect critical infrastructure configs
/config/database.yml
/config/secrets.yml

# Protect all .env files anywhere
.env*

# Protect the build directory entirely
build/

# Protect any secret keys
*.key

Configuration Best Practices

Use project config for team settings - Commit .phantom.yaml to version control
Use user config for personal preferences - Timeouts, log levels
Use hooks for quality gates - Run tests, linters before applying
Set appropriate timeouts - Prevent runaway agents
Use templates - Standardize workflows across your team