Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start: Server

Deploy Archia Server and get your first AI agent running in 5 minutes.

Prerequisites

  • Operating System: Ubuntu 24.04 LTS (or compatible Linux distribution)
  • API Key: An Anthropic API key (or other supported LLM provider)

Installation

Step 1: Install Package

sudo dpkg -i archia_0.1.0-1_amd64.deb

Step 2: Configure the Server

Create the server configuration file:

sudo vim /etc/archiad/config.toml

[network]
host = "0.0.0.0"
port = 8080

[local_inference]
max_concurrent_sessions = 4

Step 3: Create Your First Agent

Agents are configured as individual TOML files in ~/.archia/agents/. Create your first agent:

mkdir -p ~/.archia/agents
vim ~/.archia/agents/claude.toml

name = "claude"
model_name = "claude-haiku-4-5-20251001"
enabled = true
description = "A helpful AI assistant"
system_prompt = "You are a helpful, friendly assistant."

Step 4: Configure SystemD Service

Edit the systemd unit file to include your API key:

sudo vim /usr/lib/systemd/system/archiad.service

[Unit]
Description=Archia Daemon
After=network.target

[Service]
ExecStart=/usr/bin/archiad serve /etc/archiad/config.toml
Type=simple
Restart=on-failure
Environment="ANTHROPIC_API_KEY=your-api-key-here"

[Install]
WantedBy=multi-user.target

Step 5: Enable and Start the Service

sudo systemctl daemon-reload
sudo systemctl enable archiad.service
sudo systemctl start archiad.service

Step 6: Test Your Agent

Send a message to your agent:

curl -X POST http://localhost:8080/v1/chat/1/message \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claude",
    "content": [{"type": "text", "text": "Who was the first president of the United States?"}]
  }'

Expected response:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "George Washington was the first President of the United States, serving from 1789 to 1797. He was elected unanimously by the Electoral College and is often referred to as the \"Father of His Country\" for his crucial role in the American Revolution and establishing the foundations of the new federal government."
    }
  ],
  "error": null
}

Managing Agents

List Agents

# Via CLI
archiad agent list

# Via API
curl http://localhost:8080/v1/agent

Add Another Agent

Create a new agent file:

vim ~/.archia/agents/researcher.toml

name = "researcher"
model_name = "claude-sonnet-4-5-20250929"
enabled = true
description = "Research assistant with extended capabilities"

system_prompt = """
You are an expert research assistant. Your role is to:
- Provide accurate, well-sourced information
- Break down complex topics into understandable explanations
- Acknowledge uncertainty when appropriate
"""

# Grant access to MCP tools (if configured)
[mcp_tools]
web_search = null

The agent will be available immediately - no server restart required.

Next Steps