Configuration

The Archia server (archiad) uses a TOML configuration file for server settings. Agent and tool configurations are managed separately as individual TOML files.

Server Configuration

The server configuration file is provided on the command line:

archiad serve /etc/archiad/config.toml

Network Settings

Configure the HTTP server binding:

[network]
host = "0.0.0.0"
port = 8371

Local Inference Settings

Configure local model inference (if using local LLMs):

[local_inference]
max_concurrent_sessions = 4

Limits Settings

Configure default limits for chat requests:

[limits]
max_tool_calls = 10
timeout_ms = 300000

Agent Configuration

Agents are configured as individual TOML files stored in the agents directory:

• Production: ~/.archia/agents/
• Development: ~/.archia_dev/agents/

Example Agent

Create a file at ~/.archia/agents/assistant.toml:

name = "assistant"
model_name = "claude-haiku-4-5-20251001"
enabled = true
description = "A helpful AI assistant"

system_prompt = """
You are a helpful, friendly assistant. Answer questions clearly and concisely.
"""

# Optional: Grant access to specific MCP tools
[mcp_tools]
filesystem = ["read_file", "list_directory"]

Managing Agents via CLI

# List all agents
archiad agent list

# Show agent configuration
archiad agent show assistant

# Add/update an agent from a file
archiad agent set --name assistant --file ./my-agent.toml

# Remove an agent
archiad agent unset --name assistant

Managing Agents via API

# List agents
curl http://localhost:8080/v1/agent/config

# Create agent
curl -X POST http://localhost:8080/v1/agent/config \
  -H "Content-Type: application/json" \
  -d '{
    "name": "helper",
    "model_name": "claude-haiku-4-5-20251001",
    "enabled": true,
    "system_prompt": "You are a helpful assistant."
  }'

# Update agent
curl -X PUT http://localhost:8080/v1/agent/config/helper \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Delete agent
curl -X DELETE http://localhost:8080/v1/agent/config/helper

For complete agent configuration options, see Agent Configuration.

Tool Configuration

Tools (MCP servers) are configured as TOML files in the tools directory:

• User tools: ~/.archia/tools/user/{tool-name}/tool.toml
• Marketplace tools: ~/.archia/tools/{org}/{tool}/{version}/tool.toml

Example Local Tool

Create a directory and tool file at ~/.archia/tools/user/database/tool.toml:

identifier = "database"
name = "Database Tool"
description = "SQLite database access"
version = "1.0.0"
type = "mcp"

[local]
cmd = "mcp-sqlite"
args = ["--database", "/data/production.db"]
timeout_secs = 30

[local.env]
LOG_LEVEL = "info"

Example Remote Tool

identifier = "cloud-api"
name = "Cloud API"
description = "Remote API access"
version = "1.0.0"
type = "mcp"

[remote]
url = "https://api.example.com/mcp"
transport = "streaming_http"
auth_type = "bearer"
auth_token = "${API_TOKEN}"
timeout_secs = 60

Managing Tools via API

# List all tools
curl http://localhost:8080/v1/tool

# List user tools only
curl "http://localhost:8080/v1/tool?user_only=true"

# Get specific tool
curl http://localhost:8080/v1/tool/database

# Create tool
curl -X POST http://localhost:8080/v1/tool \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "my-tool",
    "name": "My Tool",
    "local": {
      "cmd": "my-mcp-server",
      "args": ["--config", "/path/to/config"]
    }
  }'

# Delete tool
curl -X DELETE http://localhost:8080/v1/tool/my-tool

For complete tool configuration options, see Tool Configuration.

System Prompts

System prompts can be stored as separate files in the prompts directory:

• Production: ~/.archia/prompts/
• Development: ~/.archia_dev/prompts/

Reference prompt files in agent configuration:

# Instead of inline system_prompt
system_prompt_file = "analyst.md"

The server will load ~/.archia/prompts/analyst.md as the system prompt.

Environment Variables

Variables

Optional Variables

Example systemd 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-anthropic-key"
Environment="OPENAI_API_KEY=your-openai-key"

[Install]
WantedBy=multi-user.target

Directory Structure Overview

~/.archia/
├── agents/                    # Agent configuration files
│   ├── assistant.toml
│   ├── researcher.toml
│   └── support.toml
├── tools/                     # Tool/MCP configurations
│   ├── user/                  # User-created tools
│   │   ├── database/
│   │   │   └── tool.toml
│   │   └── filesystem/
│   │       └── tool.toml
│   └── archia/                # Marketplace tools
│       └── web-search/
│           └── 1.0.0/
│               └── tool.toml
├── prompts/                   # System prompt files
│   ├── assistant.md
│   └── researcher.md
├── models/                    # Local model files (if using local inference)
├── supported_models.json      # Cached model registry
└── supported_tools.json       # Cached tool registry

Configuration Validation

Common configuration errors:

Next Steps

• Agent Configuration → - Complete agent configuration reference
• Tool Configuration → - Complete tool configuration reference
• REST API Reference → - API endpoint documentation
• MCPs → - MCP server setup examples