Skip to content

fawxai/fawx

BranchesTags

Repository files navigation

Fawx

CI License: BSL 1.1 Rust

Fawx is a local-first agentic engine. It runs on your machine, calls LLMs for reasoning, and executes tasks through a structured loop with built-in safety controls. One binary. Your data stays local. The agent works for you.

1,800+ tests. 34 crates. WASM skill plugins. macOS and iOS apps.

Key Features

  • Local-first — your data never leaves your machine (except to the LLM provider you choose)
  • 50+ built-in tools — file editing, shell, git, memory, Python, web browsing, and more
  • WASM skill plugins — extend capabilities with sandboxed WebAssembly modules
  • Multiple frontends — TUI, HTTP API, macOS/iOS apps, Telegram
  • Immutable safety kernel — capability gates, tripwires, and atomic ripcord rollback
  • Multi-provider LLM support — Anthropic, OpenAI, OpenRouter, Fireworks, and local models
  • Semantic memory — persistent key-value store with embeddings and decay

Table of Contents

Requirements

  • Rust (stable) — install via rustup.rs
  • macOS (Apple Silicon or Intel) or Linux
  • An API key from at least one supported LLM provider
  • wasm32-wasip1 target (optional, for building WASM skills) — rustup target add wasm32-wasip1

Quick Start

# Check prerequisites
rustc --version && cargo --version  # requires Rust stable

# Clone and build (first build takes ~2 minutes)
git clone https://github.com/fawxai/fawx.git
cd fawx && cargo build --release

# Configure (interactive wizard)
./target/release/fawx setup

# Run the server
./target/release/fawx serve

# In another terminal, start chatting
./target/release/fawx chat

# Stop the server when you're done
./target/release/fawx stop

# See all available commands
./target/release/fawx --help

Tip: Add Fawx to your PATH so fawx works from anywhere:

echo 'export PATH="$HOME/fawx/target/release:$PATH"' >> ~/.zshrc

Bring your own API key (Anthropic, OpenAI, OpenRouter, Fireworks, or local models). Fawx never sends data anywhere except the LLM provider you choose. You can also connect via the macOS/iOS app, the HTTP API, or Telegram.

Updating

cd fawx && git pull && cargo build --release

Your configuration and data in ~/.fawx/ are preserved across updates.

What It Does

Fawx runs an agentic loop: the agent reads your files, writes code, runs commands, searches memory, and calls external APIs. The kernel enforces safety boundaries so the agent operates within defined capabilities without per-action consent prompts.

You: "Find all TODO comments and summarize them"

Fawx: [search_text] Searching for TODO patterns...
      [read_file] Reading context around matches...
      [write_file] Writing summary to docs/todo-summary.md

      Found 23 TODOs across 12 files. Summary written to docs/todo-summary.md.
      Top areas: error handling (8), test coverage (6), documentation (5).

Architecture

┌──────────────────────────────────────────────────┐
│                      Shells                      │
│   TUI  ·  HTTP API  ·  macOS/iOS  ·  Telegram    │
├──────────────────────────────────────────────────┤
│                   Agentic Loop                   │
│      perceive → plan → act → synthesize          │
├──────────────┬───────────────┬────────────────────┤
│    Kernel    │     Tools     │     Loadable       │
│   (safety)   │ (50+ builtin) │   (WASM skills)    │
│              │               │                    │
│   cap gate   │  file, shell  │  web search, fetch │
│   tripwire   │  memory, git  │  weather, vision   │
│   ripcord    │  config, node │  tts, scheduler    │
├──────────────┴───────────────┴────────────────────┤
│   LLM Providers  ·  Memory  ·  Embeddings        │
│   Claude · OpenAI · OpenRouter · Fireworks        │
│   Local (llama.cpp)                               │
└──────────────────────────────────────────────────┘

Kernel (immutable at runtime)

The kernel cannot be modified by the agent. It defines the boundaries:

  • Capability Gate defines what the agent can and cannot do. Restricted actions get immediate structured denial. No modal prompts, no timeouts.
  • Tripwire silently activates monitoring when the agent crosses soft boundaries within its capability space. The agent never knows.
  • Ripcord atomically rolls back file and git operations from a tripwire point. Shell and API calls get audit-only treatment.
  • Budget Control enforces token and iteration limits to prevent runaway loops.

Loadable Layer (agent-editable)

WASM skills extend Fawx's capabilities. Each skill runs in a sandboxed WebAssembly environment with declared capabilities (network, storage). Skills are hot-reloadable and verified via Ed25519 signatures before loading.

Shells (replaceable frontends)

  • TUI for terminal users, with markdown rendering and streaming output
  • HTTP API with SSE streaming for custom integrations
  • macOS and iOS apps (native Swift)
  • Telegram and webhook channels for remote access

Built-in Tools

Category Tools
Files read_file, write_file, edit_file, list_directory, search_text
Shell run_command, exec_background, exec_status, exec_kill
Memory memory_write, memory_read, memory_list, memory_delete, memory_search
Git git_status, git_diff, git_checkpoint, git_branch_create, git_branch_switch, git_branch_delete, git_merge, git_revert, git_push, github_pr_create
Transactions begin_transaction, stage_file, commit_transaction, rollback_transaction
Scratchpad scratchpad_add, scratchpad_update, scratchpad_remove, scratchpad_list
Journal journal_write, journal_search, recall_session_context
Python python_run, python_install, python_venvs
Scheduler cron_add, cron_list, cron_get, cron_remove, cron_run, cron_history
Config config_get, config_set, fawx_status, fawx_restart
Browser web_fetch, web_search, web_screenshot
Agent spawn_agent, subagent_status, decompose, self_info, kernel_manifest, update_session_memory, current_time, notify

WASM Skills

Skills are Rust crates compiled to WebAssembly. The recommended local-dev workflow is fawx skill build <project>: it builds the project for wasm32-wasip1, installs it into ~/.fawx/skills/, and signs it when a signing key is present.

Shared skill/host contracts live in fx-protocol, including structured failure classes and HTTP envelopes used when a WASM skill needs to return more than prose across the ABI boundary.

#[no_mangle]
pub extern "C" fn run() {
    let input = get_input();
    let response = http_request("GET", &url, "", "");
    set_output(&result);
}
# Recommended local-dev workflow
cargo generate fawxai/skill-template
cd my-skill
fawx skill build .

Use the other paths when they match your input:

  • fawx skill build <project> is the canonical local-dev path for a custom skill project.
  • skills/build.sh --install is the repo maintainer path for the built-in skills/ collection.
  • fawx skill install <path> is the artifact path for a prebuilt .wasm file or skill directory.
  • fawx keys generate creates a local signing keypair and trusts the matching public key for local verification.
  • fawx sign <skill> signs an already-installed skill when it still needs a signature.

If you generate or trust a key while the server is already running, restart it before expecting the loaded skill state to flip from invalid to valid.

# Prebuilt local artifact
cargo build --release --target wasm32-wasip1
fawx skill install ./target/wasm32-wasip1/release/my_skill.wasm

# Built-in repo skills collection
skills/build.sh --install

Available skills: web search · web fetch · scheduler · weather · vision · TTS · STT · browser · canvas

LLM Providers

Provider Auth Streaming Tool Use Thinking
Anthropic Claude API key, setup token ✓ ✓ ✓
OpenAI (GPT, Codex) API key, OAuth PKCE ✓ ✓ ✓
OpenRouter API key ✓ ✓ —
Fireworks API key ✓ ✓ ✓
Local (llama.cpp) None ✓ ✓ —

Provider fallback with health tracking: if the primary provider fails, Fawx routes to the next healthy provider automatically.

Security

Fawx takes a "boundaries, not checkpoints" approach. The kernel defines what the agent can do and enforces silently. No consent prompts by default.

Capability Gate: Tools operate within declared capability spaces. Restricted actions get immediate structured denial.

Credential Store: AES-256-GCM encryption at rest, per-operation unlock. Credentials are never held in memory longer than needed.

WASM Sandboxing: Skills run in isolated environments. Only declared capabilities are granted. The host API is the sole interface.

Tripwire and Ripcord: Invisible monitoring at soft boundaries, with atomic rollback for reversible operations. The agent operates naturally while the kernel watches.

Configuration

All configuration lives in ~/.fawx/config.toml:

[llm]
default_provider = "anthropic"

[llm.anthropic]
model = "claude-sonnet-4-20250514"

[server]
host = "127.0.0.1"
port = 8400
data_dir = "~/.fawx/data"  # conversations, memory, journals

[memory]
enabled = true
embeddings_enabled = true

[permissions]
mode = "capability"  # or "prompt" for per-action approval
preset = "standard"  # open, standard, restricted

Run fawx setup for an interactive configuration wizard.

Development

# Run all tests
cargo test --workspace

# Run tests for a single crate
cargo test -p fx-kernel

# Run a specific test by name
cargo test -p fx-tools test_edit_file

# Lint (zero warnings enforced)
cargo clippy --workspace --tests -- -D warnings

# Format
cargo fmt --all

See CONTRIBUTING.md for the full development guide.

Project Structure

fawx/
├── engine/crates/           # Rust crates
│   ├── fx-kernel/           # Loop, capability gate, tripwire, ripcord
│   ├── fx-llm/              # Anthropic, OpenAI, local providers
│   ├── fx-tools/            # Built-in tool implementations
│   ├── fx-loadable/         # WASM skill runtime, hot-reload, signatures
│   ├── fx-memory/           # Key-value store with decay + embeddings
│   ├── fx-auth/             # Credential store, OAuth, setup wizard
│   ├── fx-session/          # Multi-session management
│   ├── fx-journal/          # Reflective memory
│   ├── fx-telemetry/        # Opt-in telemetry with consent persistence
│   ├── fx-api/              # HTTP API, SSE streaming, handlers
│   ├── fx-cli/              # Engine binary, headless mode
│   └── ...                  # ~24 more crates
├── skills/                  # Built-in WASM skill sources
├── app/                     # macOS and iOS native app (Swift)
├── docs/                    # Architecture, specs, design decisions
└── scripts/                 # Build and deployment

Roadmap

See docs/roadmap.html for the full roadmap. Current priorities:

  1. Open source launch with skill marketplace
  2. Attachments for images, files, and PDFs in the GUI
  3. OS-level enforcement via Landlock, seccomp, network namespaces
  4. Signal flywheel for earned autonomy through behavioral telemetry

Troubleshooting

Problem Fix
Error: no API key configured Run fawx setup or set the key directly in ~/.fawx/config.toml under the provider section.
Address already in use (port 8400) Another Fawx instance is running. Stop it with fawx stop or change the port in config.
Skill loaded but status: invalid The skill is not signed. Run fawx keys generate then fawx sign <skill>, and restart the server.
wasm32-wasip1 target not found Run rustup target add wasm32-wasip1 before building skills.
Config changes not taking effect Restart the server with fawx restart or via the fawx_restart tool.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request. Run the full test and lint suite before opening a PR:

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

License

Business Source License 1.1. Self-hosting for personal and internal business use is always permitted. The license converts to Apache 2.0 on 2030-03-23.

Skills in the fawxai organization are Apache 2.0.

About

Fawx: Free, Agentic, & WASM eXtensible

Resources

Readme

License

View license

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages