Your First Agent

Akshi agents are configured declaratively in TOML. You describe what the agent should do — its goal, which files to watch, and the LLM prompt — and the runtime handles execution, sandboxing, and inference routing. No Rust toolchain or SDK knowledge required.

1. Create a workspace

mkdir -p workspace/my-agent

2. Add something for the agent to analyze

echo "ERROR 2024-03-17 10:42:01 Connection to database timed out after 30s" > workspace/my-agent/app.log
echo "INFO  2024-03-17 10:42:05 Retry succeeded, connection restored" >> workspace/my-agent/app.log
echo "WARN  2024-03-17 10:43:12 Memory usage at 89% — approaching limit" >> workspace/my-agent/app.log

3. Write the configuration

Create config.toml:

node_id = "my-first-node"

[dashboard]
port = 3210

[router]
ollama_url = "http://127.0.0.1:11434/api/generate"
ollama_model = "llama3.2"
enable_remote = true

[[agents]]
name = "my-agent"
wasm_path = "target/wasm32-wasip1/release/agent.wasm"
workspace_dir = "./workspace/my-agent"
fuel_limit = 200000000

# Declarative agent configuration
goal = "Analyze log files and classify incidents by severity."
file_pattern = "*.log"
prompt = """You are a log analysis assistant.
For each log line, classify it as [CRITICAL], [WARNING], or [INFO].
Return one finding per line with a brief explanation."""
store_table = "findings"
store_columns = "file TEXT, severity TEXT, summary TEXT, ts INTEGER"
schedule_ms = 5000
max_iterations = 1

The key declarative fields:

Field	Description
`goal`	Human-readable description of what the agent does
`file_pattern`	Glob pattern for files the agent processes (e.g., `.log`, `.diff`)
`prompt`	System prompt sent to the LLM along with file contents
`store_table`	SQLite table where the agent stores its output
`store_columns`	Schema for the output table
`schedule_ms`	How often (in ms) the agent checks for new files
`max_iterations`	Number of processing cycles (0 = run forever)

4. Run

akshi run -c config.toml

The runtime loads the pre-built agent WASM module, reads your declarative configuration, and begins processing files in the workspace.

5. Verify

Open the dashboard at http://127.0.0.1:3210 or check from the terminal:

# Check agent status
akshi status

# Stream logs
akshi logs -f

# Query the findings database directly
sqlite3 ~/.akshi/agents/my-agent/state.db "SELECT * FROM findings;"

You should see the agent classify each log line by severity.

6. Stop

akshi stop

How it works

The pre-built akshi-agent binary (compiled to WASM) reads the declarative fields from your TOML config at runtime:

Watch — scans workspace_dir for files matching file_pattern
Analyze — sends file contents + prompt to the inference router
Store — parses the LLM response for severity markers and inserts into store_table
Report — posts findings to the dashboard API

This means you can create entirely different agents — log monitors, code reviewers, research assistants — just by changing the TOML configuration.

Going further

More templates: see Starter Agents for log-monitor, code-reviewer, test-runner, and research-lead configurations
Custom agents: if you need logic beyond declarative config, see the Rust WASM Agent guide for writing custom agents with the SDK
Configuration reference: see Agent Entry for the full list of agent configuration fields

Keyboard shortcuts

Akshi Documentation