Installation

Prerequisites

Before installing Amp, ensure you have:

PostgreSQL Required: Amp requires a PostgreSQL database for metadata storage. You’ll need PostgreSQL 12 or later.

System Requirements

Operating System: Linux (x86_64, aarch64) or macOS (Apple Silicon)
Memory: Minimum 4GB RAM (8GB+ recommended for production)
Storage: Object storage (S3, GCS, Azure) or local filesystem

PostgreSQL Setup

Amp uses PostgreSQL to store metadata about datasets, jobs, workers, and files. For development with Docker: The Amp repository includes a docker-compose.yml for local PostgreSQL:

# Clone the repository first
git clone https://github.com/edgeandnode/amp.git
cd amp

# Start PostgreSQL in the background
docker-compose up -d

This starts PostgreSQL at postgresql://postgres:postgres@localhost:5432/amp. For production: Use a managed PostgreSQL service (AWS RDS, Google Cloud SQL, Azure Database) or self-hosted PostgreSQL cluster.

Solo mode (ampd solo) can automatically manage a local PostgreSQL instance in .amp/metadb/ for zero-config development. See the Quickstart for details.

Installation Methods

Choose the installation method that best fits your workflow:

ampup

Recommended: Official version manager with automatic updates

Nix

Declarative installation for Nix users

From Source

Build manually with Cargo

Method 1: Install with ampup (Recommended)

ampup is the official version manager and installer for Amp. It handles installation, version switching, and updates.

Quick Install

curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh

This installs both ampup (the version manager) and the latest ampd and ampctl binaries.

You may need to restart your terminal or run source ~/.zshenv (or your shell’s equivalent) to update your PATH.

Custom Installation Options

The installer script accepts options for customization:

# Skip automatic PATH modification
curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh -s -- --no-modify-path

# Skip installing the latest ampd version
curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh -s -- --no-install-latest

# Use a custom installation directory
curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh -s -- --install-dir ~/.custom/amp

# Combine multiple options
curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh -s -- --no-modify-path --install-dir ~/.custom/amp

Available Options:

--install-dir <DIR>: Install to a custom directory (default: $XDG_CONFIG_HOME/.amp or $HOME/.amp)
--no-modify-path: Don’t automatically add ampup to your PATH
--no-install-latest: Don’t automatically install the latest ampd version

Managing Versions with ampup

Once installed, use ampup to manage Amp versions:

Install Latest Version

ampup install

Downloads and installs the latest release from GitHub.

Install Specific Version

ampup install v0.1.0

Install a specific tagged release.

List Installed Versions

ampup list

Shows all installed versions and indicates the active version.

Switch Between Versions

ampup use v0.1.0

Switches the active version by updating the ampd symlink.

Building from Source with ampup

ampup can also build Amp from source:

# Build from main branch (default repository)
ampup build

# Build from a specific branch
ampup build --branch develop

# Build from a Pull Request
ampup build --pr 123

# Build from a local repository
ampup build --path /path/to/amp

# Build from a custom repository
ampup build --repo username/fork --branch feature-branch

# Build with custom version name
ampup build --name my-custom-build

# Build with specific number of jobs
ampup build --jobs 8

Directory Structure

ampup creates the following directory structure:

~/.amp/
├── bin/
│   ├── ampup            # Version manager binary
│   ├── ampd             # Symlink to active version
│   └── ampctl           # Symlink to active version
├── versions/
│   ├── v0.1.0/
│   │   ├── ampd         # Binary for v0.1.0
│   │   └── ampctl       # Binary for v0.1.0
│   └── v0.2.0/
│       ├── ampd         # Binary for v0.2.0
│       └── ampctl       # Binary for v0.2.0
└── .version             # Tracks active version

Update ampup Itself

To update the ampup version manager:

ampup update

Method 2: Install via Nix

For Nix users, ampd is available as a flake:

Run Without Installing

nix run github:edgeandnode/amp

Install to Your Profile

nix profile install github:edgeandnode/amp

Try Temporarily

nix shell github:edgeandnode/amp -c ampd --version

NixOS Configuration

Add to your NixOS or home-manager configuration:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    amp = {
      url = "github:edgeandnode/amp";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { nixpkgs, amp, ... }: {
    # NixOS configuration
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      # ...
      environment.systemPackages = [
        amp.packages.${system}.ampd
      ];
    };

    # Or home-manager configuration
    home.packages = [
      amp.packages.${system}.ampd
    ];
  };
}

Nix handles version management, so ampup is not needed for Nix users.

Method 3: Build from Source (Manual)

If you prefer to build manually without using ampup:

Requirements

Rust toolchain (install from https://rustup.rs)
Git
Build dependencies (pkg-config, OpenSSL development headers)

Build Steps

Clone the Repository

git clone https://github.com/edgeandnode/amp.git
cd amp

Build the Binary

cargo build --release -p ampd

The binary will be available at target/release/ampd.

Install to PATH (Optional)

# Copy to a location in your PATH
sudo cp target/release/ampd /usr/local/bin/
sudo cp target/release/ampctl /usr/local/bin/

Verify Installation

Verify your installation by checking the version:

ampd --version

You should see output like:

ampd 0.1.0

Check available commands:

ampd --help

Output:

The blockchain native database

Usage: ampd <COMMAND>

Commands:
  solo        Start amp in local development mode
  server      Start query servers
  worker      Run distributed worker node
  controller  Run controller with Admin API
  migrate     Run migrations on the metadata database
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Environment Variables

Amp supports several environment variables for configuration:

Variable	Description	Example
`AMP_CONFIG`	Path to configuration file	`AMP_CONFIG=/etc/amp/config.toml`
`AMP_LOG`	Logging level	`AMP_LOG=info` (error, warn, info, debug, trace)
`AMP_NODE_ID`	Worker node identifier	`AMP_NODE_ID=worker-01`
`RUST_LOG`	Fine-grained log filtering	`RUST_LOG=ampd=debug,datafusion=warn`

Configuration values can also be overridden using AMP_CONFIG_* environment variables:

# Override metadata database URL
export AMP_CONFIG_METADATA_DB__URL="postgresql://user:pass@host/db"

# Override data directory
export AMP_CONFIG_DATA_DIR="/mnt/data"

# Override service addresses
export AMP_CONFIG_FLIGHT_ADDR="0.0.0.0:1602"
export AMP_CONFIG_JSONL_ADDR="0.0.0.0:1603"
export AMP_CONFIG_ADMIN_API_ADDR="0.0.0.0:1610"

For nested configuration values, use double underscores (__) to represent nesting. For example, metadata_db.url becomes AMP_CONFIG_METADATA_DB__URL.

Troubleshooting

Command not found: ampup

Make sure the ampup binary is in your PATH. Restart your terminal or run:

source ~/.bashrc  # or ~/.zshenv for zsh

Download failed

Check your internet connection
Verify the release exists on GitHub: https://github.com/edgeandnode/amp/releases
For private repos, ensure GITHUB_TOKEN is set correctly

Build from source requires Rust

If building from source, ensure you have the Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

PostgreSQL connection errors

If you see database connection errors, verify PostgreSQL is running and accessible:

psql postgresql://postgres:postgres@localhost:5432/amp -c "SELECT version();"

Uninstalling

To uninstall Amp and ampup:

# Remove the .amp directory (default installation)
rm -rf ~/.amp

# Or if you used a custom installation directory
rm -rf $XDG_CONFIG_HOME/.amp

Then remove the PATH entry from your shell configuration file (~/.bashrc, ~/.zshenv, etc.).

Next Steps

Now that Amp is installed, proceed to the quickstart:

Quickstart

Get querying blockchain data in under 5 minutes

Get Started

Core Concepts

Configuration

Querying Data

Data Sources

Administration

Deployment

​Prerequisites

​System Requirements

​PostgreSQL Setup

​Installation Methods

ampup

Nix

From Source

​Method 1: Install with ampup (Recommended)

​Quick Install

​Custom Installation Options

​Managing Versions with ampup

​Building from Source with ampup

​Directory Structure

​Update ampup Itself

​Method 2: Install via Nix

​Run Without Installing

​Install to Your Profile

​Try Temporarily

​NixOS Configuration

​Method 3: Build from Source (Manual)

​Requirements

​Build Steps

​Verify Installation

​Environment Variables

​Troubleshooting

​Command not found: ampup

​Download failed

​Build from source requires Rust

​PostgreSQL connection errors

​Uninstalling

​Next Steps

Quickstart

Build docs developers (and LLMs) love

Prerequisites

System Requirements

PostgreSQL Setup

Installation Methods

Method 1: Install with ampup (Recommended)

Quick Install

Custom Installation Options

Managing Versions with ampup

Building from Source with ampup

Directory Structure

Update ampup Itself

Method 2: Install via Nix

Run Without Installing

Install to Your Profile

Try Temporarily

NixOS Configuration

Method 3: Build from Source (Manual)

Requirements

Build Steps

Verify Installation

Environment Variables

Troubleshooting

Command not found: ampup

Download failed

Build from source requires Rust

PostgreSQL connection errors

Uninstalling

Next Steps