Quickstart

This guide walks you through creating your first resources with AgentMetal. By the end, you will have launched a virtual machine, created a VPC and database, and deployed an Infrastructure as Code stack.

Create Your First Instance

Launch a compute instance with a single command:

agentmetal instance create --name my-vm --type c2.medium --image ubuntu-22.04

This tells the Compute Agent to provision a VM with 2 vCPUs, 4 GB RAM, running Ubuntu 22.04.

Check Status

List your running instances to see the current state:

agentmetal instance list

You will see output showing the instance name, type, status, and IP address once it reaches the Running state.

Watch Agent Reasoning

Every action an agent takes is recorded in the audit log. Follow it in real time:

agentmetal audit-log --follow

You will see the Compute Agent's step-by-step reasoning: checking available hosts, selecting placement, creating the VM via libvirt, configuring networking, and verifying the instance is reachable.

Create a VPC

Isolate your resources in a Virtual Private Cloud:

agentmetal vpc create --name prod --cidr 10.0.0.0/16

The Network Agent sets up a WireGuard overlay network for secure communication between resources in this VPC.

Create a Database

Provision a managed PostgreSQL instance:

agentmetal database create --name mydb --engine postgresql --type db.medium

The Database Agent installs PostgreSQL, applies tuned configuration, sets up WAL archiving, and reports the connection string once ready.

Deploy an Infrastructure as Code Stack

Define multiple resources in a JSON file for declarative deployment. Create a file called stack.json:

{
  "resources": [
    {
      "kind": "VPC",
      "name": "app-vpc",
      "spec": { "cidr": "10.1.0.0/16" }
    },
    {
      "kind": "Subnet",
      "name": "app-web",
      "spec": {
        "vpc": "app-vpc",
        "cidr": "10.1.1.0/24",
        "type": "public"
      }
    },
    {
      "kind": "Instance",
      "name": "app-server",
      "spec": {
        "type": "c4.large",
        "image": "ubuntu-22.04",
        "subnet": "app-web"
      }
    }
  ]
}

Deploy the stack:

agentmetal iac apply stack.json

AgentMetal resolves dependencies automatically — the VPC is created first, then the subnet, then the instance is placed into the subnet.

Clean Up

When you are finished, delete the instance:

agentmetal instance delete my-vm

The Compute Agent handles graceful shutdown, resource cleanup, and IP address release.

Next Steps

• Concepts — Understand the resource model and reconciliation loop
• Compute — Full documentation for the Compute service
• Database — Full documentation for the Database service