NeuRust

An experimental Rust-based AI developer agent with Solana tooling, persistent project memory, and a full-stack local control plane.

Project status

NeuRust is an experimental portfolio project under development. It is intended to demonstrate Rust backend, CLI, AI-integration, PostgreSQL, and Solana-oriented engineering work; it is not production-ready and is not presented as a production authentication, payment, deployment, or security product.

The current portfolio scope is deliberately smaller than the original product idea. Planned surfaces such as a VS Code extension and a full synchronized dashboard are not implemented in the tracked repository.

Why NeuRust exists

NeuRust explores what an AI-assisted developer workflow looks like when the control plane is Rust-first rather than a thin scripting wrapper. The CLI can carry bounded repository context, retain small project-scoped memory, request structured plans or audits, and stream responses through a Rust/Axum service.

The project also explores Solana-focused developer ergonomics. The current implementation keeps that surface intentionally narrow: devnet-oriented CLI helpers, a browser wallet/device-link demo, and experimental backend research code rather than an autonomous deployment system.

What is implemented

Source-verified capabilities in the current repository include:

• Rust CLI with an interactive rustyline REPL and one-shot prompts.
• Streaming and non-streaming AI plan flows over HTTP/SSE.
• AI-assisted code audit workflow that optionally runs cargo audit, reads a target source file, and sends the combined context to the backend.
• Project-scoped local memory persisted in .neurust/memory.json, including a bounded rolling summary and semantic pins.
• Bounded local repository context for selected project-aware prompts.
• Structured plan application path for AI responses that contain initialization or file actions.
• Devnet-oriented Solana CLI helpers for balance checks, airdrops, and Anchor devnet deployment through the user's installed external CLIs.
• Rust/Axum backend with PostgreSQL/SQLx, embedded migrations, OpenRouter integration, AI model routing, SSE streaming, and a PostgreSQL-backed documentation knowledge store.
• Experimental documentation scraper/scheduler that stores scraped text in PostgreSQL and periodically refreshes configured sources.
• Limited Next.js web interface containing a landing page and an experimental wallet/device-link page using Solana wallet adapters.
• Next.js proxy route handlers for plan and audit requests; the current web UI does not expose a full agent dashboard.

The source also contains experimental billing/credit, admin, SOL top-up verification, and backend project-scaffolding code. Those areas are retained as research code and are not presented here as finished product features.

CLI examples

NeuRust currently uses a small custom argument/slash-command parser; it does not use Clap.

# Interactive REPL
cargo run -p neurust-cli

# One-shot AI prompt
cargo run -p neurust-cli -- "Explain the ownership issue in src/main.rs"

# Real slash commands from the current parser
cargo run -p neurust-cli -- /help
cargo run -p neurust-cli -- /auth login
cargo run -p neurust-cli -- /audit neurust-cli/src/main.rs
cargo run -p neurust-cli -- /solana help
cargo run -p neurust-cli -- /solana balance
cargo run -p neurust-cli -- /solana airdrop 2
cargo run -p neurust-cli -- /solana deploy-devnet

# Global UI flags parsed by the CLI
cargo run -p neurust-cli -- --no-stream "Review this Rust workspace structure"
cargo run -p neurust-cli -- --verbose "Explain this build error"

The explicit scaffold command is also implemented:

cargo run -p neurust-cli -- /create "Create a small Rust CLI named hello-neurust"

/create is a write-capable experimental path: it may run scaffold commands and create files in the current working area. Review the target directory and generated plan before using it.

Architecture

flowchart LR
    D[Developer]
    C["neurust-cli<br/>Rust REPL / one-shot"]
    W["neurust-web<br/>Next.js"]
    S["neurust-server<br/>Axum"]
    O[OpenRouter]
    P[(PostgreSQL)]
    K[Solana / Anchor CLIs]
    R[Solana JSON-RPC]

    D --> C
    D --> W
    C -->|HTTP + SSE| S
    W -->|device-link + proxy routes| S
    S --> O
    S --> P
    C -->|/solana helpers| K
    S -. experimental top-up verification .-> R

The main AI path is:

CLI -> Rust/Axum service -> OpenRouter, with PostgreSQL used by the service for users, usage/billing research data, device-flow state, and the documentation knowledge store. The CLI separately keeps small project-local memory on disk.

The Next.js application is currently a limited companion surface rather than a full dashboard. It provides the portfolio landing page, a devnet wallet/device-link demo, and server-side proxy handlers for plan/audit API calls.

Technology stack

• Rust 2021
• Tokio asynchronous runtime
• Axum HTTP server and SSE endpoints
• SQLx + PostgreSQL for persistence and embedded migrations
• Reqwest for OpenRouter, scraping, and Solana JSON-RPC HTTP calls
• Serde / serde_json for protocol and state serialization
• rustyline + dialoguer for terminal interaction and confirmations
• Solana tooling through external solana/anchor CLIs
• TypeScript, Next.js, React for the web surface
• @solana/web3.js + Solana wallet adapters for the devnet browser wallet demo
• Docker Compose for the local PostgreSQL service

Quick start

Prerequisites

Install:

• a stable Rust toolchain with Cargo (the repository does not currently pin a Rust version),
• Node.js and npm (the repository does not currently pin a Node version),
• Docker with the Compose plugin,
• an OpenRouter API key.

The /solana commands additionally require the Solana CLI, and /solana deploy-devnet requires Anchor CLI.

1. Clone and configure

git clone https://github.com/rock19380-ai/neurust-workspace.git
cd neurust-workspace
cp .env.example .env

Edit .env and set at minimum:

OPENROUTER_API_KEY=your_openrouter_api_key_here

The tracked .env.example contains local-development values for the Docker Compose database, model defaults, and local URLs. Do not commit .env or real credentials. The Rust server loads the root .env; the CLI and Next.js app rely on their own process environment/defaults as described below.

2. Start PostgreSQL and apply the schema

docker compose -f neurust-server/docker-compose.yml up -d db

until docker compose -f neurust-server/docker-compose.yml exec -T db \
  pg_isready -U neurust_user -d neurust_db >/dev/null 2>&1
do
  sleep 1
done

for migration in neurust-server/migrations/*.sql; do
  echo "Applying ${migration}"
  docker compose -f neurust-server/docker-compose.yml exec -T db \
    psql \
      -U neurust_user \
      -d neurust_db \
      -v ON_ERROR_STOP=1 \
      --single-transaction \
    < "${migration}"
done

NeuRust currently uses SQLx compile-time query macros without checked-in offline query metadata, so a fresh database must have the tracked schema applied before compiling the Rust workspace. The server still runs the embedded SQLx migrator during startup; the tracked migration is written to be idempotent.

3. Start the Rust server

cargo run -p neurust-server

The server connects to DATABASE_URL, runs the embedded SQLx migrator, and then starts the application.

The current server also starts the experimental documentation refresh scheduler, which performs network requests to the configured source list.

4. Install and run the web app

In another terminal:

cd neurust-web
npm ci
npm run dev

The web app defaults to http://localhost:3000. Its checked-in code already defaults to the local Rust server URLs, so no web env file is required for the default setup. To override them, create neurust-web/.env.local or export the variables before running Next.js.

5. Link the CLI development identity

In another terminal, from the repository root:

cargo run -p neurust-cli -- /auth login

The CLI prints a browser URL and device code. Open the URL, connect a development wallet, and submit the code. This flow associates a public wallet address with the device code; it does not prove wallet ownership cryptographically.

After linking:

cargo run -p neurust-cli -- "Explain this workspace architecture"

Configuration

Project-specific environment variables currently read by the code are listed below. Defaults are implementation defaults unless noted otherwise. neurust-server loads the root .env with dotenv; CLI overrides such as NEURUST_API_URL must be exported in the CLI process environment, and Next.js overrides belong in neurust-web/.env.local (or its process environment).

Repository structure

neurust-workspace/
├── Cargo.toml                 # Rust workspace: CLI + server
├── .env.example               # Local development configuration template
├── PROJECT_GOALS.md           # Scope boundaries and future direction
├── neurust-cli/               # Interactive / one-shot Rust developer CLI
│   └── src/
│       ├── commands/          # ask, audit, auth, create, Solana helpers
│       ├── api/               # Axum server HTTP/SSE client
│       └── utils/             # context, memory, command execution, REPL
├── neurust-server/            # Axum + SQLx/PostgreSQL backend
│   ├── migrations/            # Embedded SQLx schema migration
│   ├── data/sources.json      # Experimental knowledge-refresh source list
│   └── src/
│       ├── handlers/          # auth, agent, project, payment, admin routes
│       ├── middleware/        # experimental wallet-header/admin gates
│       └── services/          # AI, billing research, RAG, scraper, scheduler
└── neurust-web/               # Limited Next.js portfolio/device-link surface
    ├── app/                   # landing, login, plan/audit proxy routes
    └── components/            # landing, wallet provider, shared UI

The original VS Code extension is a roadmap item; there is no tracked extension implementation in the current repository.

Safety model

NeuRust should be treated as operator-reviewed developer tooling, not an autonomous production agent.

• In the normal ask flow, when an AI response contains an initialization command or structured plan, the CLI displays the plan and asks Apply this plan now?, defaulting to No.
• Commands classified by the CLI as heavy (cargo, npm, npx, pnpm, yarn, docker, git) present an additional run-or-skip prompt before execution.
• The explicit /create workflow is less uniformly guarded: after requesting a plan it can scaffold and write files directly, and not every possible external command is covered by the heavy-command confirmation list.
• /solana deploy-devnet intentionally invokes the user's installed Anchor CLI to build and deploy to devnet. NeuRust does not generate, import, or store Solana private keys, but the external CLI may use whatever signer the developer has configured.
• AI-generated code, audit findings, shell commands, and file changes require developer review. No claim is made that generated output is secure, correct, or suitable for production deployment.

Current limitations

• The device-link/auth path trusts an x-neurust-wallet header after a public-address linking flow. It does not perform cryptographic wallet-ownership verification and is not a production authorization boundary.
• CORS is currently permissive (Any origin, methods, and headers).
• The Next.js UI is limited to the landing page and device-link demo; there is no implemented full project/agent dashboard.
• /create and backend scaffolding are experimental write paths and do not provide a universal per-file approval model.
• The server starts the documentation refresh scheduler immediately and may perform many outbound scrape requests during development startup.
• /audit depends on an externally installed cargo-audit for dependency scanning; if unavailable, that phase is skipped.
• Solana CLI helpers require separately installed solana and anchor tools. The CLI helpers are devnet-oriented, while the experimental backend top-up verifier falls back to mainnet-beta unless SOLANA_RPC_URL is explicitly configured.
• The AI service currently enforces an English-only prompt gate.
• The Rust toolchain is not pinned. CI uses Node.js 22, but local development does not currently enforce a Node version.
• Experimental billing, admin, payment, and scraper code has not been presented or validated as a production service.

Roadmap

Future work that is not implemented today includes:

• a real VS Code extension,
• production-grade authentication and authorization,
• a full project/agent dashboard with project synchronization,
• hardened production deployment infrastructure,
• further model-provider/local-model integration beyond the current OpenRouter path.

Development verification

GitHub Actions runs the same Rust and web quality gates on pull requests and on pushes to main. The Rust job uses a disposable PostgreSQL 15 service because the checked-in SQLx query macros validate against a live schema at compile time; CI applies the tracked migrations before cargo check, Clippy, and tests. No OpenRouter key is configured, and these checks do not invoke a paid AI request.

From the repository root:

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets

For the Next.js application:

cd neurust-web
npm ci
npm run lint
npm run build
cd ..

Repository hygiene checks used for this portfolio hardening phase:

git diff --check
git status --short
git diff --stat