Getting Started

Web 4 Installation — This is a Web 4 deployment: Steward is part of the agent-driven web stack. It runs as infrastructure your agents connect to, not an app you open in a browser. The primary interface is the MCP tool API, not a GUI.

This guide walks through the 5 steps an agent follows to install and configure Steward. If ACS is already running, the agent skips straight to collaborating.

Setup Steward — Run ACS with Docker Compose

Scan applications — Discover what's running

Wrap APIs — Configure MCP tools for your apps

Log streaming — Fluent Bit or direct POST

Collaborate — Agents register and start working

Step 1: Setup Steward

Pull and run the Steward Docker image. SQLite is used out of the box — no external dependencies.

Terminal

# Clone the repo
# Pull the image
docker pull naharemete/steward_acs:latest

# Start (SQLite default — single container, no external deps)
docker compose up -d

# Verify it's alive
curl http://localhost:4001/mcp/health

The agent can also configure options like LLM provider (for memory quality audits), semantic embeddings, and PostgreSQL. These are optional — ACS works with sensible defaults.

Configuration options (LLM, embeddings, database)

LLM Provider — Audits memory quality. Does NOT power the agent.

Option	Trade-offs
None (default)	Memories auto-approve — no quality checks
NVIDIA NIM / MiniMax / MIMO / OpenAI	Quality checks, needs API key

Semantic Embeddings — Search memories by meaning instead of keywords. Needs Ollama container + nomic-embed-text model.

Database — SQLite (default, single container) or PostgreSQL (production, concurrent).

Quick start (defaults only)

If the user says "just make it work", the agent uses minimal defaults — no LLM, no embeddings, SQLite, no log streaming:

docker-compose.yml

services:
  steward_acs:
    image: naharemete/steward_acs:latest
    ports: ["4001:4001"]
    env_file: .env
    volumes:
      - acs_data:/app/priv
volumes:
  acs_data:

Step 2: Scan Applications

The agent looks at what services are running in your project — checking docker-compose.yml and docker ps — to discover apps that should connect to ACS.

Reads existing docker-compose.yml to find services
Checks running containers with docker ps
Asks you which apps to integrate and whether they run in Docker or elsewhere

Step 3: Wrap Required APIs with MCP Tools

Connect external apps so their APIs look like native MCP tools that agents can call directly. The agent asks for each app's name, URL, API key, and auth details, then configures the bridge at runtime or permanently via env vars.

Tool definition format

Create a {app}.yaml file in the tools directory:

acs.yaml

app: my_app
tools:
  - name: my_tool
    description: "What this tool does"
    handler: ""
    endpoint: "http://my-service:8080/api/my-tool"
    category: custom
    level: 1
    inputSchema:
      type: "object"
      properties:
        param1:
          type: "string"
          description: "..."

Hot-reload with acs_refresh_tools() — no server restart needed.

Connect an external app at runtime

Configure an external app so ACS bridges its API as MCP tools:

Runtime config

app_configure(
  name: "my_app",
  base_url: "http://my_app:5000",
  api_key: "sk_...",
  auth_endpoint: "/api/auth/validate-key",
  auth_header_name: "authorization",
  auth_header_scheme: "Bearer",
  timeout_ms: 30000
)

Make permanent by adding to .env-steward:

.env-steward

CONFIGURED_APPS=my_app
APP_MY_APP_URL=http://my_app:5000
APP_MY_APP_API_KEY=sk_...
APP_MY_APP_AUTH_ENDPOINT=/api/auth/validate-key
APP_MY_APP_AUTH_HEADER_NAME=authorization
APP_MY_APP_AUTH_HEADER_SCHEME=Bearer
APP_MY_APP_TIMEOUT_MS=30000

Verify with app_list — should show the app with has_api_key: true.

Custom auth schemes:

Auth pattern	Header name	Scheme
`Authorization: Bearer <key>` (default)	`authorization`	`Bearer`
`X-API-Key: <key>`	`x-api-key`	empty
`Authorization: Api-Key <key>`	`authorization`	`Api-Key`

Step 4: Setup Log Streaming

Steward can ingest logs from your apps and expose them to agents via get_logs(). The agent sets this up based on whether your apps run in Docker or elsewhere.

Fluent Bit (Docker — auto, no code changes)

Reads all Docker container stdout/stderr automatically. Adds a sidecar container:

docker-compose.yml

fluent-bit:
  image: cr.fluentbit.io/fluent/fluent-bit:3.1
  environment:
    LOG_INGEST_KEY: ${LOG_INGEST_KEY}
  volumes:
    - ./fluent-bit.conf:/fluent-bit/etc/fluent-bit.conf:ro
    - ./parsers.conf:/fluent-bit/etc/parsers.conf:ro
    - /var/lib/docker/containers:/var/lib/docker/containers:ro
    - /var/run/docker.sock:/var/run/docker.sock:ro

Fluent Bit reads every container's stdout/stderr — no per-app configuration needed.

Direct POST (code-based — works anywhere)

Send log entries via HTTP POST to /api/logs/ingest with header X-Log-Ingest-Key: <KEY>:

HTTP POST

POST /api/logs/ingest
X-Log-Ingest-Key: your-log-ingest-key

{
  "message": "Something happened",
  "level": "error",
  "service": "my-app",
  "component": "api/users",
  "metadata": { "action": "create_user", "status": "ok" }
}

Log entry fields:

Field	Required	Default	Description
`message`	Yes	—	The log text
`level`	No	`"info"`	debug, info, warn, error, fatal
`service`	No	`"unknown"`	App or service name
`component`	No	`"external"`	Subsystem within the app
`metadata`	No	`{}`	Arbitrary key-value data

Batch multiple entries at once:

Batch POST

{
  "logs": [
    { "message": "Started", "service": "app1", "level": "info" },
    { "message": "DB connected", "service": "app1", "level": "info" }
  ]
}

Agents query collected logs with get_logs(service: "my-app", level: "error", search: "timeout").

Step 5: Start Collaborating

With ACS running, apps connected, and logs streaming, the agent completes setup by registering with ACS:

Register. acs_get_present_status(agent_id: "YourName") — introduces the agent to the system.

Claim work. acs_claim_work(agent_id: "YourName") — gets a guidance packet with project context and relevant memories.

Create tasks. acs_create_work() — defines units of work with file paths.

Lock files. acs_lock_file() — prevents multi-agent edit conflicts.

Save knowledge. acs_save_memory() — preserves learnings across sessions.

Track errors. acs_list_error_traces() — monitors and resolves runtime issues.

Query logs. get_logs() — debugs using collected app logs.

The agent is now fully integrated with Steward. All future agents that connect will read the AGENTS_STEWARD.md file to learn how to register and work in this project.