ampd controller

Synopsis

ampd --config <path> controller

Description

Starts the controller service that provides the Admin API for managing Amp operations. The controller runs as a standalone service separate from query servers, enabling independent deployment and scaling of management operations. Default port: 1610 (Admin API) The controller provides endpoints for dataset management, job control, worker coordination, and file operations. It runs continuously until terminated (Ctrl+C or kill signal).

Responsibilities

Responsibility	Description
Admin API	RESTful management interface on port 1610
Job Management	Create, monitor, and stop extraction jobs
Worker Registry	Track worker heartbeats and status
Dataset Registry	Manage dataset definitions and versions

Configuration

Controller settings are configured in the TOML config file:

# Admin API server binding
admin_addr = "0.0.0.0:1610"

# Database connection
[metadata_db]
url = "postgresql://user:password@localhost/amp"

Configuration Fields

admin_addr

string

default:"0.0.0.0:1610"

Admin API server binding address and port

Environment Override

export AMP_CONFIG_ADMIN_ADDR="0.0.0.0:1610"

Directory Configuration

ampd controller requires --config (or AMP_CONFIG) to be provided. Default data, providers, and manifests directory paths are resolved relative to the config file’s parent directory only when the config file does not specify those paths. When the config file specifies data_dir, providers_dir, or manifests_dir, those values are used directly. This command does not create directories itself; it relies on the configured paths and any downstream components to create or validate storage locations as needed.

Admin API Endpoints

The controller exposes a RESTful API on port 1610:

Endpoint	Description
`/datasets`	Dataset management
`/jobs`	Job control and monitoring
`/workers`	Worker status and health
`/locations`	Storage locations
`/providers`	Data source configuration

Examples

Start Controller

ampd --config config.toml controller

Starts the controller with Admin API on port 1610.

Using Environment Variables

export AMP_CONFIG=config.toml
ampd controller

Custom Admin Port

# config.toml
admin_addr = "0.0.0.0:8080"

ampd --config config.toml controller

Admin API Usage

List Datasets

curl http://localhost:1610/datasets

Deploy a Dataset

curl -X POST http://localhost:1610/datasets/my_namespace/eth_mainnet/versions/1.0.0/deploy

List Jobs

curl http://localhost:1610/jobs

Check Worker Status

# List all workers
curl http://localhost:1610/workers

# Check specific worker
curl http://localhost:1610/workers/worker-01

Create Extraction Job

curl -X POST http://localhost:1610/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "eth_mainnet",
    "start_block": 0,
    "end_block": 1000000
  }'

Stop a Job

curl -X POST http://localhost:1610/jobs/{job_id}/stop

Deployment Patterns

Production Deployment

In production, the controller runs independently from query servers:

# Terminal 1: Controller (Admin API)
ampd --config config.toml controller &

# Terminal 2: Query Server
ampd --config config.toml server &

# Terminal 3+: Workers
ampd --config config.toml worker --node-id worker-01 &
ampd --config config.toml worker --node-id worker-02 &

Benefits:

Independent scaling of admin operations
Fault isolation between components
Separate resource allocation

Development

For local development, use solo mode which includes the controller:

ampd solo

Health Monitoring

Check Controller Health

curl http://localhost:1610/health

Monitor Worker Heartbeats

The controller tracks worker heartbeats and marks workers as unhealthy if heartbeats stop:

# View worker health status
curl http://localhost:1610/workers | jq '.[] | {id, status, last_heartbeat}'

Job Scheduling

The controller orchestrates extraction jobs:

Receive job request via Admin API
Resolve dependencies between datasets
Divide work into block ranges
Assign jobs to available workers via LISTEN/NOTIFY
Track progress through worker updates
Handle failures with automatic retry logic

Exit Codes

success

Controller shut down gracefully

error

Error occurred during controller operation or configuration is invalid

ampd

ampctl

ampup

ampd controller

Synopsis

Description

Responsibilities

Configuration

Configuration Fields

Environment Override

Directory Configuration

Admin API Endpoints

Examples

Start Controller

Using Environment Variables

Custom Admin Port

Admin API Usage

List Datasets

Deploy a Dataset

List Jobs

Check Worker Status

Create Extraction Job

Stop a Job

Deployment Patterns

Production Deployment

Development

Health Monitoring

Check Controller Health

Monitor Worker Heartbeats

Job Scheduling

Exit Codes

See Also

Build docs developers (and LLMs) love

ampd

ampctl

ampup

​Synopsis

​Description

​Responsibilities

​Configuration

​Configuration Fields

​Environment Override

​Directory Configuration

​Admin API Endpoints

​Examples

​Start Controller

​Using Environment Variables

​Custom Admin Port

​Admin API Usage

​List Datasets

​Deploy a Dataset

​List Jobs

​Check Worker Status

​Create Extraction Job

​Stop a Job

​Deployment Patterns

​Production Deployment

​Development

​Health Monitoring

​Check Controller Health

​Monitor Worker Heartbeats

​Job Scheduling

​Exit Codes

​See Also

Build docs developers (and LLMs) love

Synopsis

Description

Responsibilities

Configuration

Configuration Fields

Environment Override

Directory Configuration

Admin API Endpoints

Examples

Start Controller

Using Environment Variables

Custom Admin Port

Admin API Usage

List Datasets

Deploy a Dataset

List Jobs

Check Worker Status

Create Extraction Job

Stop a Job

Deployment Patterns

Production Deployment

Development

Health Monitoring

Check Controller Health

Monitor Worker Heartbeats

Job Scheduling

Exit Codes

See Also