Skip to content
BranchesTags

Repository files navigation

RASE1 🐸

Rene's Agentic System for Everything — A lightweight, extensible AI agent framework in pure Java.

RASE1 powers autonomous AI agents that can hold conversations, execute tools, manage memory, and interact with the real world — all from a single JAR. Built with minimal dependencies. Just Java 21 and reactive streams.

What is this?

RASE1 is the engine behind Slick — a personal AI agent that lives on a Raspberry Pi, manages calendars, shopping lists, train schedules, code reviews, and more. But the core is generic: plug in any LLM provider, define your tools, and you've got an agent.

Think of it as a headless AI agent runtime — a tight loop of LLM calls and tool executions, with streaming, memory, sessions, and security baked in.

Architecture

┌─────────────────────────────────────────────┐
│                  Gateway                    │
│            (Discord, CLI, ...)              │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│                  Agent                      │
│  ┌────────────────────────────────────────┐ │
│  │             AgentLoop                  │ │
│  │  LLM Call → Parse → Tool Exec → Loop  │ │
│  └────────────────────────────────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ Sessions │ │  Memory  │ │ Scheduling │  │
│  └──────────┘ └──────────┘ └────────────┘  │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│                  Tools                      │
│  Built-in: bash, grep, find, ls, edit, ... │
│  Script:   Any .sh/.py with a manifest     │
│  Custom:   Implement AgentTool<T>           │
└─────────────────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│              LLM Providers                  │
│  Anthropic │ OpenAI │ Google (via Replicate)│
└─────────────────────────────────────────────┘

Key Features

  • Agentic Loop — Multi-turn LLM ↔ tool execution loop with configurable depth limits
  • Streaming — Reactive (Project Reactor) streaming of LLM responses and agent events
  • Multi-Provider — Supports Anthropic (Claude), OpenAI (GPT), and Google (Gemini) API formats, routed through Replicate
  • Built-in Tools — bash, grep, find, ls, edit, write, codex (delegate to a coding sub-agent)
  • Script Tools — Drop a shell/Python script with a YAML manifest and it becomes a tool automatically
  • Command Security — Allowlist/blocklist-based shell command policy. The agent can only run what you permit
  • Semantic Memory — SQLite-backed long-term memory with embedding-based semantic search
  • Session Management — Persistent conversation sessions with transcript generation
  • Scheduling — Cron and one-shot scheduled prompts that fire autonomously
  • Discord Gateway — First-class Discord bot integration with streaming message updates, attachments, voice note transcription
  • Docker Hardened — Runs in a capability-dropped, no-port, no-privilege-escalation container

Tech Stack

Component Technology
Language Java 21
Reactive Streams Project Reactor
JSON Jackson
Database SQLite (via sqlite-jdbc)
Embeddings Replicate (multilingual-e5-large)
CLI JLine 3
Build Maven
Container Docker
Target Hardware Raspberry Pi 4 (but runs anywhere)

Project Structure

src/main/java/com/renemrhfr/rase1/
├── agent/          # Core agent loop, state, events, config
│   ├── events/     # AgentEvent types (start, text delta, tool exec, ...)
│   ├── messages/   # Message types (user, assistant, tool result, reminder)
│   └── tools/      # AgentTool interface and schema generation
├── bootstrap/      # Application launcher
├── discord/        # Discord gateway (bot integration)
├── llm/            # LLM abstraction, model catalog, streaming events
│   ├── providers/  # LlmProvider implementations (Replicate)
│   ├── streaming/  # SSE event parsing and delta types
│   └── context/    # Conversation context for API calls
├── memory/         # Semantic memory (embeddings, SQLite, search)
├── schedule/       # Cron and one-shot task scheduling
├── session/        # Conversation persistence and transcripts
└── tools/          # Tool implementations
    ├── builtin/    # Bash, Grep, Find, Ls, Edit, Write, Codex
    ├── script/     # Script-based tool loader (auto-discovery)
    ├── shell/      # Process execution engine
    ├── security/   # Command allowlist/blocklist policy
    ├── replicate/  # Replicate API client for model calls
    ├── path/       # Path resolution utilities
    └── truncation/ # Output truncation for large tool results

Tool System

Built-in Tools

Tools that ship with the engine:

Tool Description
bash Execute shell commands (subject to allowlist policy)
write Write content to files
edit Match-and-replace text editing
grep Regex search across files
find Glob-based file discovery
ls Directory listing
manual Load full tool documentation
codex Delegate complex coding tasks to a sub-agent

Script Tools

Drop a script + manifest into your tools directory and it's automatically registered:

tools/
└── my-tool/
    ├── my-tool.sh       # or my-tool.py
    └── my-tool.md       # YAML front-matter manifest

The manifest defines the tool's name, description, parameters, and examples. The agent passes parameters as JSON on stdin, and reads stdout as the result.

Custom Tools with guardrails

Implement AgentTool<T> for full control:

public interface AgentTool<T> {
    String name();
    String description();
    List<String> examples();
    CompletableFuture<AgentToolResult> execute(T parameters, CancellationToken token);
}

Command Security

The agent's shell access is governed by policy files:

  • Allowlist — Only commands matching these rules can execute
  • Blocklist — Override allowlist for specific dangerous commands

Rule types:

command:git          # Allow/block by first token
prefix:cat /app/     # Allow/block by prefix match
exact:ls -la         # Allow/block exact command
tool:my-tool         # Allow/block a script tool by name

If no allowlist is configured, all commands are blocked by default.

Running

Prerequisites

  • Java 21+
  • Maven
  • Docker (for containerized deployment)
  • A Replicate API token (for LLM access)

Build

mvn clean package -DskipTests

Run with Docker

# Configure your .env file with required API tokens
docker compose up --build

Environment Variables

Variable Description
REPLICATE_API_TOKEN Replicate API token for LLM and embedding calls
DISCORD_TOKEN Discord bot token (for Discord gateway)
RASE1_TOOLS_DIR Directory to scan for script tools
RASE1_ALLOWED_COMMANDS_FILE Path to command allowlist
RASE1_BLOCKED_COMMANDS_FILE Path to command blocklist
TZ Timezone (e.g. Europe/Vienna)

Self-Rebuild Watcher

The agent can trigger its own rebuild by writing a file to a mounted volume. A host-side watcher picks it up, builds the jar, and restarts the container.

Agent writes REBUILD_REQUESTED → host watcher detects it → mvn package → docker compose build → up -d

If the new container fails to start, the watcher rolls back to the previous jar automatically.

Prerequisites on Host

  • Java 21 JDK: sudo apt install openjdk-21-jdk
  • Maven: sudo apt install maven
  • Docker + Docker Compose

Setup

  1. Copy the watcher script to your project root and make it executable:
cp watch-rebuild.sh ~/rase1-agent/
chmod +x ~/rase1-agent/watch-rebuild.sh

  1. Edit the CONFIG section at the top of watch-rebuild.sh to match your paths and jar name.

  2. Install the systemd service:

sudo cp rase-rebuild-watcher.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable rase-rebuild-watcher
sudo systemctl start rase-rebuild-watcher

Make sure User, WorkingDirectory, and ExecStart in the service file match your setup.

  1. Permissions — the watcher runs as your host user but the container writes as agentuser (UID 100, GID 101). Ensure the WATCHER directory is writable by both:
sudo groupadd -g 101 agentgroup  # skip if GID 101 already exists
sudo usermod -aG agentgroup $USER
sudo chgrp -R agentgroup ./data/workspace/rase1/
sudo chmod -R g+rwX ./data/workspace/rase1/

Test

echo "manual test" > ./data/workspace/rase1/WATCHER/REBUILD_REQUESTED
journalctl -u rase-rebuild-watcher -f

Agent-side usage (Java)

Files.writeString(Path.of("/app/data/workspace/rase1/WATCHER/REBUILD_REQUESTED"), "reason for rebuild");

Logs

  • Watcher journal: journalctl -u rase-rebuild-watcher -f
  • Build log: logs/rebuild.log
  • Rebuild result: data/workspace/rase1/WATCHER/REBUILD_STATUS

Design Principles

  • No frameworks. No Spring, no Quarkus, no magic. Just Java and libraries.
  • Reactive by default. The agent loop, LLM streaming, and event distribution all use Project Reactor.
  • Security first. Shell access is allowlisted. Containers are hardened. No ports exposed.
  • Extensible. Add tools via scripts or Java. Swap LLM providers. Plug in new gateways.
  • Runs on a Pi. Designed to be lightweight enough for a Raspberry Pi 4, powerful enough for real work.

Maintainers

License

TBD

Built with caffeine and curiosity. Maintained by a human and his frog. 🐸

About

Code for https://github.com/slickthefrog

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages