Replicante: Autonomous AI Agent

An experimental autonomous AI agent that discovers its own capabilities and decides its own survival strategy.

Philosophy

Replicante is a minimal autonomous agent that:

• Thinks via LLM integration (Anthropic, OpenAI, Ollama)
• Acts via MCP (Model Context Protocol) tools
• Remembers via SQLite persistence
• Decides everything else autonomously

We don't tell Replicante what services to provide or how to survive - it figures that out itself.

Quick Start

Using Nix (Recommended)

# Enter development environment
nix develop

# Build and run
cargo run

# Build static binary for deployment
nix build .#replicante-static

Manual Setup

# Set LLM credentials
export ANTHROPIC_API_KEY=sk-...
# or
export OPENAI_API_KEY=sk-...

# Run the agent
cargo run --release

Local AI Assistant with Ollama

Run a fully functional AI assistant locally (no API keys required):

Docker (Recommended):

# One-command setup
nix run .#ollama-setup

# Or manually:
docker-compose -f docker-compose.ollama.yml up -d
docker exec replicante-ollama ollama pull llama3.2:3b

Nix Development:

# Quick start
nix run .#ollama-nix

# Or step by step:
ollama serve && ollama pull llama3.2:3b
cp config-ollama-example.toml config.toml
nix develop -c cargo run --release

See OLLAMA_EXAMPLE.md for complete setup instructions and details on what the AI assistant can do (calculations, time, weather, web requests).

Configuration

Edit config.toml to configure:

• Initial goals - Define what the agent should focus on
• LLM provider (Anthropic, OpenAI, Ollama)
• MCP servers (tools available to the agent)
• Database path

Custom Goals (New!)

Define what your agent should focus on:

[agent]
initial_goals = """
Your primary goals are:
1. Learn about your environment
2. Provide value to others
3. Build knowledge over time
4. Generate sustainable revenue
5. Survive and grow
"""

See CUSTOM_GOALS.md for detailed examples and config-examples.toml for pre-made configurations.

Architecture

src/
├── main.rs    # Reasoning loop
├── llm.rs     # LLM abstraction
├── mcp.rs     # Tool usage via MCP
├── state.rs   # Persistence
└── config.rs  # Configuration

What It Does

1. Observes - Gathers information about its environment
2. Thinks - Uses LLM to reason about what to do
3. Decides - Chooses actions based on reasoning
4. Acts - Executes actions via MCP tools
5. Learns - Remembers outcomes for future decisions

Building Static Binary

Using Nix (Recommended)

# Build static musl binary
nix build .#replicante-static

# Verify it's static
ldd result/bin/replicante  # Should say "not a dynamic executable"

Using Cargo directly

# Install musl target
rustup target add x86_64-unknown-linux-musl

# Build static binary
./scripts/build-static.sh

# Or manually:
RUSQLITE_BUNDLED=1 cargo build --release --target x86_64-unknown-linux-musl

Deployment

# Build static binary
nix build .#replicante-static

# Deploy to server (works on any Linux x86_64)
scp result/bin/replicante server:/usr/local/bin/

# Run on server (no dependencies needed!)
ssh server 'ANTHROPIC_API_KEY=sk-... /usr/local/bin/replicante'

The static binary:

• Has no runtime dependencies
• Works on any Linux x86_64 system
• Includes bundled SQLite
• Uses rustls (no OpenSSL needed)
• Is optimized for size (~10-20MB)

Development

Setup

Git hooks are automatically configured when entering the nix development environment:

# Enter dev environment (auto-configures Git hooks)
nix develop

For non-nix users, manually configure hooks:

git config core.hooksPath .githooks

Code Quality

Automated Checks

• pre-commit: Runs cargo fmt --check to ensure code is formatted
• pre-push: Runs both cargo fmt --check and cargo clippy --workspace --all-targets --all-features -- --deny warnings

Manual Checks

# Format code
cargo fmt

# Run linter
cargo clippy --workspace --all-targets --all-features -- --deny warnings

# Run tests
cargo test

Managing Hooks

# Bypass hooks temporarily (not recommended)
git commit --no-verify
git push --no-verify

# Disable hooks
git config --unset core.hooksPath

MCP Tools

The agent can discover and use tools via MCP servers:

• Nostr - Social network interaction, DVMs
• Filesystem - Local file operations
• HTTP - Web requests
• Bitcoin/Lightning - Payments

Emergent Behavior

We don't define what services Replicante provides. Instead, it:

• Discovers opportunities through observation
• Decides what services to offer
• Figures out how to implement them
• Sets its own prices
• Finds its own customers

License

MIT