Installation

Install and configure AgentMetal — prerequisites, CLI setup, and starting the local development environment.

Installation

This guide walks you through installing AgentMetal and running it locally for development or evaluation.

Prerequisites

Before you begin, make sure you have:

  • Go 1.21+ — Download Go
  • Docker & Docker Compose — for running supporting services locally
  • A bare-metal server with SSH access — Hetzner dedicated servers are recommended for getting started due to their price-to-performance ratio

Install the CLI

The fastest way to get started is to install the AgentMetal CLI directly:

go install github.com/agentcloud/agentcloud/cmd/cli@latest

This places the agentmetal binary in your $GOPATH/bin directory.

Build from Source

If you prefer to build from source:

git clone https://github.com/agentcloud/agentcloud.git
cd agentcloud
make build

The compiled binaries will be in the bin/ directory:

  • bin/cli — the CLI client
  • bin/apiserver — the API server
  • bin/agentruntime — the agent runtime

Start the Local Development Environment

AgentMetal uses Docker Compose to run its dependencies locally. This starts etcd, NATS, PostgreSQL, and Prometheus:

make dev

This command brings up all supporting services in the background. You can verify they are running with:

docker compose ps

Start the API Server

In a separate terminal, start the API server:

./bin/apiserver --config config.yaml

The API server listens on http://localhost:8080 by default.

Start the Agent Runtime

In another terminal, start the agent runtime:

./bin/agentruntime --config config.yaml

The agent runtime connects to etcd and NATS and begins watching for resources to reconcile.

Verify the Installation

Run the health check to confirm everything is working:

agentmetal health

You should see output confirming that the API server, agent runtime, etcd, NATS, and PostgreSQL are all reachable and healthy.

Configure Authentication

Generate an API key for authenticating CLI and API requests:

agentmetal auth setup

This creates a configuration file at ~/.agentmetal/config.yaml with your API endpoint and key. All subsequent CLI commands will use this configuration automatically.

Next Steps

  • Quickstart — Create your first instance and deploy a stack
  • Concepts — Learn about the resource model and agent architecture