Overview

our-agent run agent.conf          # CLI interactive
our-agent build agent.conf        # Package as executable
our-agent export agent.conf       # Export as Skill / MCP

Write a .conf file to define your AI agent. One config, many runtimes.

Quick Start

npm install -g our-agent          # Install via npm
# or from source:
# git clone https://github.com/stevenwang15/our-agent && cd our-agent
# ./install.sh                    # macOS / Linux
# .\install.ps1                   # Windows (PowerShell)

# Set your API key
export OUR_AGENT_KEY="sk-your-key"

# Run an example
our-agent run examples/translator.conf

.conf Format

Two styles — use whichever you prefer:

Bracket style:

[agent]
name = translator
desc = Professional translator

[prompt]
system = "You are a professional translation assistant."
welcome = "Enter text to translate."

[settings]
provider = openai
temperature = 0.3

[tools]
allow = web_search, current_time

[ui]
icon = 🌐
color = #22c55e

Brace style:

agent {
    name = "translator";
    desc = "Professional translator";

    prompt {
        system = "You are a professional translation assistant.";
        welcome = "Enter text to translate.";
    }

    settings {
        provider = "openai";
        temperature = 0.3;
    }
}

Key rule: never store API keys, models, or base URLs in .conf — these are injected at runtime via environment variables or CLI flags.

CLI Commands

| Command | Description | |---------|-------------| | run <file> | Run an agent (interactive or one-shot with -P) | | build <file> | Package as standalone executable (macOS / Windows / Linux) | | export <file> | Export as Skill JSON or MCP server | | lint <file> | Validate .conf syntax | | init [name] | Scaffold a new agent config | | providers | List all supported LLM providers |

Run Examples

# Interactive mode
our-agent run agent.conf

# One-shot prompt
our-agent run agent.conf -P "Translate: Hello World"

# Custom provider
our-agent run agent.conf --provider deepseek
our-agent run agent.conf --provider ollama --base-url http://localhost:11434/v1

# With env vars (don't hardcode in .conf)
OUR_AGENT_KEY=sk-xxx our-agent run agent.conf

Build Executable

# Build for current platform
our-agent build agent.conf -o ./dist

# Build for specific target
our-agent build agent.conf -t win-x64 -o ./dist
our-agent build agent.conf -t linux-x64 -o ./dist
our-agent build agent.conf -t mac-arm64 -o ./dist

Export

# Export as Skill
our-agent export agent.conf -f skill -o ./exports

# Export as MCP server
our-agent export agent.conf -f mcp -o ./exports

# Export all formats
our-agent export agent.conf -o ./exports

Supported Providers

| Provider | Default Model | Auth | |----------|--------------|------| | openai | GPT-4o | Bearer token | | anthropic | Claude 3.5 Sonnet | x-api-key | | google | Gemini 1.5 Pro | Bearer token | | deepseek | DeepSeek V3 | Bearer token | | ollama | llama3 | None (local) | | openrouter | auto | Bearer token |

Built-in Tools

| Tool | Description | License | |------|-------------|---------| | web_search | Web search via DuckDuckGo | MIT (duck-duck-scrape) | | read_file | Read files (cwd only) | Built-in | | write_file | Write files (cwd only) | Built-in | | list_files | List directory contents | Built-in | | execute_command | Run shell commands | Built-in | | current_time | Get current date/time | Built-in |

Installation

From npm (recommended)

npm install -g our-agent

From source (macOS / Linux)

git clone https://github.com/stevenwang15/our-agent && cd our-agent
./install.sh

From source (Windows)

git clone https://github.com/stevenwang15/our-agent; cd our-agent
.\install.ps1

Manual

git clone https://github.com/stevenwang15/our-agent && cd our-agent
npm install
npm install -g .

Uninstall

npm uninstall -g our-agent
# or: ./uninstall.sh        # macOS / Linux

Project Structure

our-agent/
├── bin/our-agent.js           # CLI entry point
├── src/
│   ├── conf/parser.js         # .conf parser
│   ├── runtime/               # Engine, LLM, tools, session
│   └── commands/              # CLI command implementations
├── examples/                  # Sample .conf files
├── install.sh / install.ps1   # Install scripts
├── uninstall.sh               # Uninstall script
└── LICENSE                    # Apache 2.0

Why .conf?

• One format, multiple runtimes — CLI, export, package
• Secrets-free — no keys, models, or URLs in config files
• Composable — mix sections, include files, override at runtime

License

Apache 2.0 — see LICENSE.