Quickstart Guide

Build and test your first METAOS agent in under 5 minutes.

1. Install the CLI

npm install -g @metaoslabs/cli

Or for local development:

git clone https://github.com/BilBillions/metaos-labs-site
cd metaos-labs-site/cli
npm install
npm link

2. Initialize Your Project

mkdir my-agent && cd my-agent
metaos init

This creates a metaos.json configuration file:

{
  "backendUrl": "http://localhost:3001",
  "authToken": null,
  "agents": []
}

3. Start the Backend (Local Testing)

In the backend directory, start the development server:

cd metaos-labs-site/backend
pnpm install
pnpm prisma:generate
pnpm start:dev

# Backend starts on http://localhost:3001/v1

Note: Requires PostgreSQL with pgvector. Configure backend/.env first.

4. Test Your First Agent

Run an agent with the CLI. The backend currently supports storage.write for demo purposes:

metaos agent run travel --intent notes.write "Trip to Paris - remember Eiffel Tower"

# Output:
# 🤖 Running agent: travel
# 📝 Intent: notes.write
# 📦 Args: Trip to Paris - remember Eiffel Tower
# 
# ┌─────────────────────────────────────┐
# │  ✅ Saved to notes                  │
# │  📁 Path: metaos://notes/travel...  │
# │  📊 Size: 43 bytes                  │
# └─────────────────────────────────────┘

5. Understanding the Zero-Trust Flow

Here's what happens when you run an agent:

1. CLI sends HTTP POST to /v1/tools/call with JWT token
2. Tool Gateway validates: Agent installed → Capability granted → Policy check
3. Policy decides: ALLOW (read ops), REQUIRE_APPROVAL (writes), or DENY (dangerous)
4. If allowed, executes tool and logs to audit table
5. Returns result: {success:true, data:{...}}
6. CLI displays formatted output card

6. Production Use

For production, update your metaos.json to point to the live backend:

{
  "backendUrl": "https://metaos-backend.onrender.com/v1",
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agents": []
}

Get your JWT token from /v1/auth/login or the dashboard.

Next Steps