Chapter 2: Installation and Setup #

"Before you can run, you must build."

In this chapter, you will install Neam's dependencies, build the toolchain from source, verify the build, configure your editor for Neam development, and set up the environment variables needed to connect to LLM providers. By the end, you will have a working Neam installation and will compile and run your first program.

2.1 What You Are Building #

Before diving into installation steps, it is worth understanding exactly what the Neam build process produces. Unlike Python-based agent frameworks where you pip install a library and remain inside the Python ecosystem, building Neam gives you a complete, self-contained toolchain -- nine executables and a shared library that together form the most comprehensive compiled infrastructure for AI agent development available today.

2.1.1 The Neam Toolchain at a Glance #

The total native binary footprint for the entire Neam toolchain is approximately 9.1 MB for a deployment bundle (the VM plus a compiled .neamb file). To put this in perspective:

These numbers are not theoretical -- they come from measured benchmarks comparing equivalent B5-class agent programs (six agents, five handoffs, RAG, voice, and MCP integration). The dramatic size difference is a direct consequence of Neam's compiled architecture: there is no interpreter, no package dependency tree, no virtual environment overhead.

2.1.2 Startup Performance #

The deployment size advantage translates directly into startup speed, which is critical for serverless functions, edge computing, and autoscaled Kubernetes pods:

Python's startup cost comes from importing the interpreter, loading the framework module tree (LangChain alone pulls in hundreds of transitive dependencies), and initializing the runtime. Neam's VM loads pre-compiled bytecode and begins execution immediately -- the entire startup path is a single mmap of the .neamb file followed by a jump to the entry point.

2.1.3 The Standard Library #

Beyond the core toolchain, Neam includes a standard library of 445+ modules organized across 27 domains. These modules are written in Neam itself and ship in the stdlib/ directory:

You do not need to install these separately -- they are bundled with the Neam repository and available via import in any Neam program:

import "stdlib/rag/agentic.neam"
import "stdlib/agents/analyst.neam"
import "stdlib/ingest/pdf.neam"

2.1.4 What the Toolchain Provides #

The Neam compiler and runtime are written in C++20 and implement the following major subsystems:

You do not need to understand the implementation details to use Neam effectively -- the toolchain handles everything behind a clean compilation interface. The build process compiles all of these subsystems into the nine executables listed in Section 2.1.1.

2.2 System Prerequisites #

Neam is written in C++20 and uses CMake as its build system. The build process automatically downloads and compiles all third-party dependencies, so you only need three things installed on your system:

Additionally, the build requires development headers for two system libraries:

The following sections walk through installing these prerequisites on each platform.

2.3 macOS Setup #

macOS is Neam's primary development platform. The fastest path is to install Xcode Command Line Tools (which provides Clang) and then use Homebrew for the remaining dependencies.

Step 1: Install Xcode Command Line Tools #

Open Terminal and run:

xcode-select --install

This installs Clang (Apple's C++ compiler), make, git, and other essential development tools. Follow the on-screen prompts to complete the installation.

Verify the installation:

clang++ --version

You should see output indicating Apple Clang version 15 or later (which supports C++20).

Step 2: Install Homebrew #

If you do not already have Homebrew installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 3: Install Dependencies #

brew install cmake curl openssl

Step 4: Verify Prerequisites #

cmake --version      # Should be 3.20+
clang++ --version    # Should support C++20 (Apple Clang 15+)
git --version        # Any recent version

2.4 Linux Setup #

Neam builds on any Linux distribution with a C++20 compiler. The instructions below cover the two most common package managers.

Debian / Ubuntu (apt) #

sudo apt update
sudo apt install -y build-essential cmake git libcurl4-openssl-dev libssl-dev

This installs GCC (with C++20 support), CMake, Git, libcurl development headers, and OpenSSL development headers.

Fedora / RHEL / CentOS (yum/dnf) #

sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y cmake git libcurl-devel openssl-devel

On older CentOS versions that use yum instead of dnf, replace dnf with yum.

Arch Linux (pacman) #

sudo pacman -S base-devel cmake git curl openssl

Verify Prerequisites #

g++ --version        # Should be GCC 12+ (or clang++ 15+)
cmake --version      # Should be 3.20+
git --version
pkg-config --libs libcurl    # Should output -lcurl
pkg-config --libs openssl    # Should output -lssl -lcrypto

2.5 Windows Setup #

Neam supports two compiler toolchains on Windows: MSVC (Visual Studio) and MinGW. MSVC is recommended for the simplest experience.

Option A: Visual Studio (MSVC) #

1. Download and install Visual Studio 2022 or later (Community edition is free). During installation, select the "Desktop development with C++" workload.

2. Install CMake from https://cmake.org/download/ (or use the version bundled with Visual Studio).

3. Install Git from https://git-scm.com/download/win.

4. Install vcpkg for managing libcurl and OpenSSL:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg install curl:x64-windows openssl:x64-windows

1. Open a Developer Command Prompt for VS (or x64 Native Tools Command Prompt) and proceed to the build instructions in Section 2.6.

Option B: MinGW (MSYS2) #

1. Download and install MSYS2 from https://www.msys2.org/.

2. Open the MSYS2 MinGW 64-bit shell and install dependencies:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake \
          mingw-w64-x86_64-curl mingw-w64-x86_64-openssl git

1. Proceed to the build instructions in Section 2.6.

2.6 Building from Source #

With prerequisites installed, building Neam is a three-command process.

Step 1: Clone the Repository #

git clone https://github.com/neam-lang/Neam.git
cd Neam

Step 2: Configure with CMake #

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

During the cmake configuration step, CMake will automatically download and build the following third-party dependencies using FetchContent:

Additionally, Neam bundles the SQLite3 amalgamation in deps/sqlite3/ for persistent memory and cognitive feature storage.

Step 3: Build #

cmake --build . --parallel

The --parallel flag uses all available CPU cores. On a modern machine, the build typically takes 2-5 minutes.

Optional CMake Flags #

Neam's build system supports several optional flags for enabling cloud backends (introduced in v0.6.5):

Example with PostgreSQL and Redis enabled:

cmake .. -DCMAKE_BUILD_TYPE=Release \
         -DNEAM_BACKEND_POSTGRES=ON \
         -DNEAM_BACKEND_REDIS=ON

For the exercises in this book, the default build (no extra flags) is sufficient.

2.7 Verifying the Build #

After a successful build, verify that all executables were produced:

ls -la neamc neam neam-cli neam-api neam-pkg neam-lsp neam-dap neam-forge neam-gym

On macOS and Linux, you should also see the shared library:

ls -la libneam.*    # libneam.dylib (macOS) or libneam.so (Linux)

On Windows (MSVC), the library is neam.dll.

Quick Smoke Test #

Create a file called hello.neam in the build directory (or any directory):

{
  emit "Hello, Neam!";
}

Compile and run:

./neamc hello.neam -o hello.neamb
./neam hello.neamb

Expected output:

Hello, Neam!

If you see this output, your Neam installation is working correctly.

Running the Test Suite #

To run the built-in tests and verify that the VM, compiler, and standard library are functioning correctly:

ctest --output-on-failure

This runs all registered tests: vm_test, compiler_test, async_unit_test, runtime_executor_test, stdlib_list_test, stdlib_map_test, type_unification_test, test_framework_test, and io_file_test.

All tests should pass. If any test fails, check the output for details and ensure your compiler and system libraries meet the minimum version requirements.

Build Verification Benchmarks #

Once your build is complete, it is useful to verify that your installation meets the expected performance characteristics. These benchmarks were measured on representative hardware and published in the Neam architecture paper (Govindaraj et al., 2026). Your numbers may vary depending on hardware, but the relative ratios should be consistent.

Compilation performance:

You can measure compilation time with:

time ./neamc program.neam -o program.neamb

Memory footprint (Resident Set Size):

You can measure RSS with:

# macOS
/usr/bin/time -l ./neam program.neamb 2>&1 | grep "maximum resident set size"

# Linux
/usr/bin/time -v ./neam program.neamb 2>&1 | grep "Maximum resident set size"

Per-turn orchestration overhead (non-LLM operations):

For comparison, the same operations in Python+LangChain total approximately 260 μs -- a 38x difference. At scale (50 iterations with 100 concurrent agents), this adds up: Neam completes non-LLM orchestration in 34.5 ms versus Python's 1,300 ms.

Compile-Time Error Detection #

One of Neam's most significant advantages over Python-based frameworks is its ability to catch agent configuration errors at compile time, before any code runs or any LLM API calls are made. The compiler validates 12 categories of errors that Python discovers only at runtime (if at all):

This means that when neamc compiles your program without errors, you can be confident that the agent topology is valid, all handoff targets exist, all tool schemas are well-formed, and all provider configurations are complete. You will never discover at 3 AM that a production agent fails because a handoff target was misspelled.

2.8 Setting Up Your Editor #

Neam ships with an LSP server (neam-lsp) that provides IDE support. This section covers VS Code setup, which is the most common configuration.

VS Code Setup #

1. Install the Neam extension (if available in the marketplace), or configure a generic LSP client.

2. Configure the LSP client. Add the following to your VS Code settings.json:

{
  "neam.lsp.path": "/path/to/your/build/neam-lsp",
  "files.associations": {
    "*.neam": "neam"
  }
}

Replace /path/to/your/build/neam-lsp with the actual path to the neam-lsp executable in your build directory.

1. Configure the debugger. Create a .vscode/launch.json file in your project:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "neam",
      "request": "launch",
      "name": "Debug Neam Program",
      "program": "${workspaceFolder}/program.neamb",
      "dapExecutable": "/path/to/your/build/neam-dap"
    }
  ]
}

Other Editors #

The LSP server works with any editor that supports the Language Server Protocol:

• Neovim: Use nvim-lspconfig and add a custom server configuration pointing to neam-lsp.
• Emacs: Use lsp-mode or eglot and register neam-lsp as a language server.
• Sublime Text: Use the LSP package and add a custom client configuration.

Adding Neam to Your PATH #

For convenience, add the build directory to your shell's PATH so you can invoke Neam tools from any directory:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="/path/to/Neam/build:$PATH"

After sourcing the file or opening a new terminal, you can use:

neamc program.neam -o program.neamb
neam program.neamb
neam-cli --watch program.neam

2.9 Environment Variables for LLM Providers #

Neam agents connect to LLM providers via HTTP APIs. Each provider requires an API key (except Ollama, which runs locally). Neam implements a uniform adapter interface across all providers -- the same agent declaration works with any provider by changing a single line. The VM handles the protocol differences between providers so you do not have to.

2.9.1 Provider Capabilities #

Each provider adapter implements a common interface but offers different capabilities:

All providers support the same Neam agent declaration syntax. Switching providers requires changing only the provider and model fields:

agent MyAgent {
  provider: "anthropic"        // was: "openai"
  model: "claude-sonnet-4-20250514"  // was: "gpt-4o"
  system: "You are a helpful assistant."
}

2.9.2 API Keys and Authentication #

Set the following environment variables to enable the providers you intend to use:

Setting Environment Variables #

macOS / Linux (bash or zsh):

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="AI..."

Source the file:

source ~/.zshrc    # or source ~/.bashrc

Windows (PowerShell):

$env:OPENAI_API_KEY = "sk-..."
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:GEMINI_API_KEY = "AI..."

For persistent environment variables on Windows, use the System Properties dialog (search for "Environment Variables" in the Start menu).

Ollama Setup #

Ollama runs LLMs locally on your machine. It requires no API key, making it ideal for development, testing, and privacy-sensitive applications.

1. Install Ollama from https://ollama.com/

2. Pull a model:

ollama pull llama3
ollama pull qwen2.5:14b
ollama pull qwen3:1.7b          # Lightweight model for development
ollama pull nomic-embed-text    # For RAG embeddings

1. Verify Ollama is running:

curl http://localhost:11434/api/tags

By default, Ollama listens on http://localhost:11434. If you change the host or port, set the OLLAMA_HOST environment variable:

export OLLAMA_HOST="http://custom-host:11434"

Testing Your Provider Setup #

Create a test file test_provider.neam:

agent TestBot {
  provider: "openai"
  model: "gpt-4o-mini"
  system: "Reply with exactly: Provider working."
}

{
  let response = TestBot.ask("Test");
  emit response;
}

Compile and run:

neamc test_provider.neam -o test_provider.neamb
neam test_provider.neamb

If the output includes "Provider working" (or a similar response), your API key is configured correctly. Repeat with provider: "anthropic", provider: "gemini", and provider: "ollama" to verify each provider.

2.10 Using Pre-Built Binaries #

2.10.1 GitHub-Based Installer (Recommended) #

Starting with v0.6.5 (spec v0.13), Neam provides a portable installer script that downloads pre-built binaries directly from GitHub Releases with built-in checksum verification and auditable receipts. The installer follows a defense-in-depth approach: TLS-only downloads, SHA-256 verification, no curl | sh, and dry-run by default.

The installer script is located at scripts/neam-install.sh in the Neam repository.

Plan mode (dry-run) -- preview what will happen without installing:

./scripts/neam-install.sh --version v0.6.5

This prints the computed download URLs, the target install directory, and the tools required for installation, without downloading or writing anything. Always run plan mode first to verify the configuration.

Execute mode -- perform the installation:

./scripts/neam-install.sh --version v0.6.5 --execute

This downloads the platform-specific tarball, verifies the SHA-256 checksum against the published SHA256SUMS file, extracts the binaries to a versioned directory (default: /usr/local/neam/v0.6.5), creates symlinks for neam and neamc, and emits an install receipt for auditability. The install to /usr/local may require sudo.

Custom install directory (no sudo required):

./scripts/neam-install.sh --version v0.6.5 --install-dir "$HOME/.local/neam" --execute

SHA-256 checksum verification is performed automatically during --execute mode. You can also verify manually after a download:

# Download the checksum file
curl -LO https://github.com/neam-lang/Neam/releases/download/v0.6.5/SHA256SUMS

# Verify the tarball
sha256sum -c SHA256SUMS --ignore-missing

Optional GPG signature verification:

./scripts/neam-install.sh --version v0.6.5 \
    --gpg-keyring /path/to/neam-maintainers.gpg \
    --execute

Key installer flags:

Directory layout after installation:

Add the installed binaries to your PATH:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="/usr/local/neam/v0.6.5/bin:$PATH"

# Or if using a custom install directory:
export PATH="$HOME/.local/neam/v0.6.5/bin:$PATH"

2.10.2 Manual Download (Alternative) #

If you prefer not to use the installer script, pre-built binaries are also available for manual download from the GitHub Releases page:

https://github.com/neam-lang/Neam/releases

Each release includes binaries for:

• macOS (arm64 / Apple Silicon)
• macOS (x86_64 / Intel)
• Windows (x64, MSVC)
• Linux (x86_64)

Download the archive for your platform, extract it, and add the extracted directory to your PATH:

# macOS / Linux example
tar xzf neam-v0.6.5-macos-arm64.tar.gz
cd neam-v0.6.5-macos-arm64
export PATH="$(pwd):$PATH"

# Verify
neamc --version
neam --version

Pre-built binaries include all nine executables and the shared library. They are built with the default configuration (HNSW enabled, cloud backends disabled).

2.11 Troubleshooting Common Build Issues #

CMake version too old #

Symptom: CMake Error: CMake 3.20 or higher is required.

Fix: Upgrade CMake. On macOS: brew upgrade cmake. On Linux:

pip install cmake --upgrade
# or download from https://cmake.org/download/

CURL not found #

Symptom: Could NOT find CURL (missing: CURL_LIBRARY CURL_INCLUDE_DIR)

Fix: Install libcurl development headers.

• macOS: brew install curl
• Debian/Ubuntu: sudo apt install libcurl4-openssl-dev
• Fedora: sudo dnf install libcurl-devel

OpenSSL not found #

Symptom: Could NOT find OpenSSL

Fix: Install OpenSSL development headers.

• macOS: brew install openssl and set: bash export OPENSSL_ROOT_DIR=$(brew --prefix openssl)
• Debian/Ubuntu: sudo apt install libssl-dev
• Fedora: sudo dnf install openssl-devel

C++20 not supported #

Symptom: error: 'optional' is not a member of 'std' or similar C++20 errors.

Fix: Upgrade your compiler.

• GCC: version 12 or later (sudo apt install g++-12 or later)
• Clang: version 15 or later
• MSVC: Visual Studio 2022 or later

uSearch compilation failure on MinGW #

Symptom: Template errors in usearch/index.hpp when cross-compiling for Windows.

Fix: This is expected. The build system automatically disables HNSW when cross-compiling for Windows with MinGW. If you see this error in a non-cross-compilation scenario, add -DNEAM_USE_HNSW=OFF to your CMake command.

Download failures during cmake #

Symptom: FetchContent fails to download dependencies.

Fix: Check your internet connection and proxy settings. If you are behind a corporate firewall, configure CMake's proxy:

export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

Alternatively, you can manually download the dependency tarballs and place them in the build/_deps/ directory before running cmake.

Permission denied when running executables #

Symptom: Permission denied when running ./neamc or ./neam on macOS or Linux.

Fix:

chmod +x neamc neam neam-cli neam-api neam-pkg neam-lsp neam-dap neam-gym

macOS Gatekeeper blocks execution #

Symptom: "neamc" can't be opened because Apple cannot check it for malicious software.

Fix: Right-click the executable, select "Open", and confirm. Or remove the quarantine attribute:

xattr -d com.apple.quarantine neamc neam neam-cli neam-api neam-pkg neam-lsp neam-dap neam-gym

2.12 Project Directory Structure #

When working on Neam projects, the recommended directory structure is:

my-agent-project/
  neam.toml              # Project manifest (created by neam-pkg init)
  src/
    main.neam            # Entry point
    agents/
      triage.neam        # Agent definitions
      specialists.neam
    tools/
      search.neam        # Tool definitions
    skills/
      summarize.neam     # Skill definitions
    guards/
      content_policy.neam  # Guard/policy definitions
    knowledge/
      docs.neam          # Knowledge base definitions
  data/
    docs/                # Documents for RAG ingestion
  tests/
    test_triage.neam     # Test files
  .neam/
    traces/              # Auto-generated trace logs
    memory/              # SQLite memory files
    bundles/             # Compiled bundles (.neamb archives)

Initialize a new project:

neam-pkg init my-agent-project
cd my-agent-project

This creates the neam.toml manifest and a basic src/main.neam file.

2.13 Your First Real Program #

Let us end this chapter by building something that actually talks to an LLM. This requires at least one provider to be configured (see Section 2.9).

Create src/main.neam:

agent Greeter {
  provider: "ollama"
  model: "llama3"
  system: "You are a friendly assistant. Keep your responses to one sentence."
}

{
  emit "--- Neam Agent Test ---";
  let response = Greeter.ask("What is the most interesting thing about programming languages?");
  emit "Agent says: " + response;
  emit "--- Done ---";
}

Compile and run:

neamc src/main.neam -o main.neamb
neam main.neamb

You should see output similar to:

--- Neam Agent Test ---
Agent says: The most interesting thing about programming languages is how they
shape the way we think about problems and solutions.
--- Done ---

Congratulations. You have just built and run your first AI agent in Neam.

2.14 Understanding the Cost Advantage #

Now that you have a working Neam installation, it is worth understanding the economic implications of the toolchain you just built. The following total cost of ownership (TCO) model, based on a production B5-class agent system (6 agents, 5 handoffs, RAG, voice, MCP integration, 10,000 daily interactions), quantifies the difference:

The infrastructure savings come directly from Neam's memory efficiency: a Neam agent system runs comfortably in a 256 MB container, while the equivalent Python system requires a 2 GB instance. On cloud infrastructure priced per GB-hour, this is a 9x reduction in compute cost.

The debugging savings reflect the compile-time error detection discussed in Section 2.7. With Python, misconfigured handoffs, missing tool schemas, and invalid provider references surface as runtime errors -- often in production, often at 3 AM. With Neam, the compiler catches these before deployment.

2.15 What Comes Next #

The next chapter explores the Neam language in depth: variables, types, expressions, control flow, functions, and all the foundational syntax you need before building more complex agent systems.

At this point you have:

• A complete Neam toolchain (9 executables + shared library)
• At least one configured LLM provider
• A verified build with passing tests
• An editor configured with LSP support
• Your first compiled and executed Neam agent program

You are ready to write Neam.

Exercises #

Exercise 2.1: Build from Source #

Clone the Neam repository, build it from source, and verify that all nine executables are produced. Record:

1. Your operating system and version
2. Your compiler version
3. Your CMake version
4. The total build time (use time cmake --build . --parallel)
5. The sizes of the neamc and neam executables

Exercise 2.2: Provider Configuration #

Set up at least two LLM providers (choose from OpenAI, Anthropic, Gemini, Ollama). Write a Neam program that queries both providers and prints their responses:

agent ProviderA {
  provider: "openai"
  model: "gpt-4o-mini"
  system: "Identify yourself as Provider A."
}

agent ProviderB {
  provider: "ollama"
  model: "llama3"
  system: "Identify yourself as Provider B."
}

{
  emit "Provider A: " + ProviderA.ask("Who are you?");
  emit "Provider B: " + ProviderB.ask("Who are you?");
}

Exercise 2.3: Watch Mode #

Use neam-cli --watch to run a program in watch mode. While it is running, modify the agent's system prompt and save the file. Observe the automatic recompilation and re-execution. Answer:

1. How quickly does the watch mode detect changes?
2. What happens if you introduce a syntax error?
3. What happens if you fix the syntax error?

Exercise 2.4: Build Flags #

Rebuild Neam with NEAM_USE_HNSW=OFF and observe the difference:

cmake .. -DCMAKE_BUILD_TYPE=Release -DNEAM_USE_HNSW=OFF
cmake --build . --parallel

1. How does the build time change?
2. Do all tests still pass?
3. What impact does this have on RAG functionality?

Exercise 2.5: Toolchain Exploration #

Run each of the following commands and describe what they do:

./neam-api --help
./neam-pkg --help
./neam-gym --help
./neam-cli --help

For neam-api, start the server on port 8080 and use curl to query the health endpoint:

./neam-api --port 8080 &
curl http://localhost:8080/api/v1/health

Document the response format.

Exercise 2.6: Bytecode Inspection #

Compile the hello world program and examine the .neamb file:

./neamc hello.neam -o hello.neamb
xxd hello.neamb | head -20

1. Can you identify the NEAM magic header in the hex dump?
2. Can you spot the string "Hello, Neam!" in the constant pool section?
3. How large is the .neamb file compared to the .neam source?