neko

Lightweight AI agent runtime targeting Raspberry Pi Zero 2W and low-end VPS. File-based memory, MCP tool support, Telegram integration — all in a single binary.

Install

Shell (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/superhq-ai/neko/main/install.sh | sh

Installs to ~/.local/bin by default. Override with NEKO_INSTALL_DIR:

NEKO_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/superhq-ai/neko/main/install.sh | sh

From source:

git clone https://github.com/superhq-ai/neko.git
cd neko
cargo build --release
# binary at target/release/neko

Quick start

# Create default config and workspace
neko init

# Or run interactive setup
neko init --interactive

# Edit config (defaults to ~/.neko/config.toml)
neko config edit

# Start the agent gateway
neko start

# Send a test message
neko message "Hello, what can you do?"

Configuration

Config lives at ~/.neko/config.toml. Key sections:

[gateway]
bind = "127.0.0.1:3000"
workspace = "~/.neko/workspace"

[agent]
model = "gpt-5-mini"
provider = "openai"
max_tokens = 4096
tools = ["read_file", "write_file", "list_files", "exec", "http_request", "memory_write"]

[providers.openai]
api_key = "${OPENAI_API_KEY}"
base_url = "https://api.openai.com"

[tools]
sandbox = false
exec_timeout_secs = 1800

# MCP servers
[mcp.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

Environment variables are substituted via ${VAR_NAME} syntax.

CLI

neko init              Initialize config and workspace
neko init -i           Interactive setup
neko start             Start the gateway server
neko stop              Stop the running gateway
neko status            Show gateway status
neko logs [-l N]       Show recent logs
neko message     Send a message to the agent
neko config show       Print current config
neko config edit       Open config in $EDITOR
neko sessions list     List active sessions
neko sessions clear    Clear all sessions
neko memory list       List memory files
neko memory search Q   Search memory files
neko skills list       List installed skills
neko skills install P  Install a skill from path
neko skills remove N   Remove a skill by name
neko cron list         List all cron jobs
neko cron add  Add a scheduled job
neko cron edit     Edit a cron job
neko cron remove   Remove a cron job
neko cron history      Show execution history

Features

OpenResponses-compatible LLM

Works with any provider exposing POST /v1/responses — OpenAI, Anthropic (via proxy), Ollama, or self-hosted models.

File-based memory