llm9p

LLM access via the 9P filesystem protocol.

llm9p enables users, scripts, and AI agents to interact with Large Language Models through standard filesystem operations. Write a prompt to a file, read the response from the same file. Supports multiple backends including Anthropic API, Claude Code CLI, and local LLMs (planned).

Supported Backends

| Backend | Status | Description | |---------|--------|-------------| | Anthropic API | Available | Direct API access with your API key | | Claude Code CLI | Available | Uses Claude Max subscription via claude command | | Local LLMs (Ollama) | Planned | Run models locally without cloud dependencies |

The pluggable backend architecture makes it easy to add new LLM providers.

What is 9P?

9P is a simple, lightweight network filesystem protocol originally developed for Plan 9 from Bell Labs. It lets you access remote resources as if they were local files. This means you can interact with LLMs using basic file operations (cat, echo, >, <) instead of SDKs or HTTP APIs.

Why use 9P for LLM access?

• Universal: Any language or tool that can read/write files can use it
• Scriptable: Chain LLM calls with standard Unix pipes and shell scripts
• Composable: Mount multiple 9P services and combine them
• Simple: No libraries, no dependencies, just files

Installation

go install github.com/NERVsystems/llm9p/cmd/llm9p@latest

Or build from source:

git clone https://github.com/NERVsystems/llm9p
cd llm9p
go build -o llm9p ./cmd/llm9p

Usage

Start the Server

Option A: Using Anthropic API (requires API key)

export ANTHROPIC_API_KEY=sk-ant-...
./llm9p -addr :5640

Option B: Using Claude Max Subscription (via Claude Code CLI)

If you have a Claude Max subscription and the Claude Code CLI installed:

./llm9p -addr :5640 -backend cli

This uses your Claude Max subscription instead of API tokens. No API key required.

Requirements for CLI backend:

• Claude Code CLI installed and authenticated (claude command available)
• Active Claude Max subscription

Mount the Filesystem

There are several ways to mount the filesystem depending on your environment.

Option 1: Plan 9 from User Space (plan9port)

plan9port provides Plan 9 tools for Unix systems.

# Install on macOS
brew install plan9port

# Install on Debian/Ubuntu
sudo apt-get install 9base

# Mount using 9pfuse
mkdir -p /mnt/llm
9pfuse localhost:5640 /mnt/llm

# Or use the 9p tool directly (no mount needed)
9p -a localhost:5640 ls llm
9p -a localhost:5640 read llm/model
9p -a localhost:5640 write llm/ask "What is 2+2?"
9p -a localhost:5640 read llm/ask

Option 2: Infernode (Inferno OS)

Infernode is a hosted Inferno OS environment with native 9P support. This is an excellent way to explore 9P filesystems.

# Start infernode
cd /path/to/infernode
./emu

# Inside infernode shell, mount llm9p
# Note: Use IP address 127.0.0.1, not "localhost"
mkdir /n/llm
mount -A tcp!127.0.0.1!5640 /n/llm

# List available files
ls -l /n/llm

# Check current model
cat /n/llm/model

# Ask a question
echo 'What is the capital of France?' > /n/llm/ask
cat /n/llm/ask

# View conversation history
cat /n/llm/context

# Reset conversation
echo reset > /n/llm/new

Infernode Tips:

• Always use 127.0.0.1 instead of localhost for the server address
• Create the mount point with mkdir /n/llm before mounting
• The -A flag to mount enables anonymous authentication (no auth required)
• Use single quotes around prompts to avoid shell interpretation issues

Option 3: Linux 9P Mount

Linux has built-in 9P filesystem support via the 9p kernel module.

# Mount via kernel 9p module
sudo mount -t 9p -o port=5640,version=9p2000 localhost /mnt/llm

Interact with the LLM

# Ask a question
echo "What is 2+2?" > /mnt/llm/ask
cat /mnt/llm/ask

# View token usage
cat /mnt/llm/tokens

# Change model
echo "claude-3-haiku-20240307" > /mnt/llm/model

# Adjust temperature
echo "0.5" > /mnt/llm/temperature

# Set a system prompt (persists across conversation resets)
echo "You are a helpful coding assistant." > /mnt/llm/system

# View current system prompt
cat /mnt/llm/system

# View conversation history
cat /mnt/llm/context

# Add a system message
echo "You are a helpful coding assistant." > /mnt/llm/context

# Reset conversation
echo "" > /mnt/llm/new

# View help
cat /mnt/llm/_example

Filesystem Schema

/llm/
├── ask              # Write prompt, read response (same file)
├── model            # Read/write: current model name
├── temperature      # Read/write: temperature float (0.0-2.0)
├── system           # Read/write: system prompt (persists across resets)
├── tokens           # Read-only: last response token count
├── new              # Write anything to start fresh conversation
├── context          # Read: conversation history; Write: add system message
├── _example         # Read-only: usage examples
└── stream/          # Streaming interface
    ├── ask          # Write-only: starts a streaming request
    └── chunk        # Read-only: blocks until next chunk, EOF on completion

File Behaviors

| File | Read | Write | |------|------|-------| | ask | Returns last LLM response | Sends prompt to LLM (sync), stores response | | model | Returns current model name | Sets model for subsequent requests | | temperature | Returns current temperature | Sets temperature (0.0-2.0) | | system | Returns current system prompt | Sets system prompt (persists across resets) | | tokens | Returns last response token count | Permission denied | | new | Permission denied | Any write resets conversation (keeps system prompt) | | context | Returns JSON conversation history | Appends system message to history | | _example | Returns usage examples | Permission denied | | stream/ask | Permission denied | Starts a streaming request | | stream/chunk | Blocks until next chunk, returns it | Permission denied |

Streaming

For long responses, use the streaming interface to see output as it's generated:

# Start a streaming request (using 9p tool)
echo "Write a poem about the moon" | 9p -a localhost:5640 write stream/ask &

# Read chunks as they arrive
while chunk=$(9p -a localhost:5640 read stream/chunk 2>/dev/null); do
  [ -z "$chunk" ] && break
  printf "%s" "$chunk"
done

With a mounted filesystem:

# Start streaming in background
echo "Explain quantum computing" > /mnt/llm/stream/ask &

# Read chunks
while read -r chunk < /mnt/llm/stream/chunk 2>/dev/null; do
  printf "%s" "$chunk"
done

Note: Start reading chunks immediately after writing to stream/ask. If you wait too long, the stream may complete and you'll get EOF.

Shell Scripting

#!/bin/sh
# ask.sh - Simple LLM query script

if [ -z "$1" ]; then
    echo "Usage: $0 <question>"
    exit 1
fi

echo "$1" > /mnt/llm/ask
cat /mnt/llm/ask

Configuration

Command Line Flags

| Flag | Default | Description | |------|---------|-------------| | -addr | :5640 | Address to listen on | | -backend | api | Backend: api (Anthropic API) or cli (Claude Code CLI) | | -debug | false | Enable debug logging |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | For api backend | Your Anthropic API key |

Default Settings

• Model: claude-sonnet-4-20250514 (API) or sonnet (CLI)
• Temperature: 0.7
• Max Tokens: 4096

Backend Differences

| Feature | API Backend | CLI Backend | |---------|-------------|-------------| | Authentication | API key required | Claude Max subscription | | Token counting | Accurate | Not available (always 0) | | Model names | Full names | Aliases (opus, sonnet, haiku) | | Streaming | True streaming | Simulated (full response) | | Rate limits | API limits apply | Subscription limits apply |

Requirements

• Go 1.21+
• LLM backend (one of the following):
  • Anthropic API key (for api backend)
  • Claude Code CLI with Max subscription (for cli backend)
• 9P client (one of the following):
  • plan9port - Plan 9 tools for Unix (macOS, Linux)
  • Infernode - Hosted Inferno OS with native 9P
  • Linux 9P kernel module - Built into Linux kernel
  • Native Plan 9 or Inferno OS

Troubleshooting

Port already in use

# Check what's using the port
lsof -i :5640

# Use a different port
./llm9p -addr :5641

Connection refused

Ensure the server is running and listening on the expected port:

# Start with debug logging to see connections
./llm9p -addr :5640 -debug

Infernode: "localhost" not resolving

Inferno's DNS resolution works differently. Use the IP address directly:

# Wrong
mount -A tcp!localhost!5640 /n/llm

# Correct
mount -A tcp!127.0.0.1!5640 /n/llm

Infernode: Mount point doesn't exist

Create the mount point before mounting:

mkdir /n/llm
mount -A tcp!127.0.0.1!5640 /n/llm

Permission denied on write

Some files are read-only by design:

• tokens - Read-only (token count from last response)
• _example - Read-only (usage examples)
• stream/chunk - Read-only (streaming output)

Empty response from ask

The ask file only contains content after you write a prompt to it:

# First write a prompt
echo "Hello" > /mnt/llm/ask

# Then read the response
cat /mnt/llm/ask

API errors

Check that your API key is set and valid:

# Ensure the key is exported
export ANTHROPIC_API_KEY=sk-ant-...

# Verify it's set
echo $ANTHROPIC_API_KEY

How It Works

1. Server starts: llm9p listens for 9P connections on the specified port
2. Client connects: A 9P client (9pfuse, Infernode, etc.) connects and negotiates the protocol
3. Filesystem exposed: The client sees a virtual filesystem with files like ask, model, tokens
4. Write prompt: Writing to ask sends the text to the configured LLM backend
5. Read response: Reading from ask returns the LLM's response
6. State persists: Conversation history is maintained until you write to new

The 9P protocol handles all the complexity of making this look like a regular filesystem, so any tool that can read and write files can interact with the LLM.

Related Projects

• Infernode - Hosted Inferno OS with native 9P support
• plan9port - Plan 9 from User Space
• u9fs - 9P file server

License

MIT