Claude Slim Server

A lightweight HTTP server for the Claude Code SDK that enables AI-powered coding assistance in any environment - Docker, Caprover, or standalone Node.js.

Features

• Simple HTTP API with Server-Sent Events (SSE) streaming
• Secure by default with path validation and sensitive file protection
• Flexible deployment - Docker, npm package, or direct Node.js
• Tool restrictions - Control which Claude tools are available
• Authentication support - Optional Bearer token authentication
• Programmatic API - Use as a library in your applications

Installation

As a global npm package

npm install -g claude-slim-server

As a dependency in your project

npm install claude-slim-server

Using Docker

docker pull yourusername/claude-slim-server
docker run -p 9999:9999 -v $(pwd):/app yourusername/claude-slim-server

Quick Start

Command Line Usage

# Start with defaults
claude-slim-server

# Specify port and working directory
claude-slim-server --port 8080 --cwd /workspace

# Enable authentication
claude-slim-server --auth-token mysecrettoken

# Limit available tools
claude-slim-server --tools "Read,Write,Edit"

Programmatic Usage

import { createClaudeSlimServer } from 'claude-slim-server';

const server = createClaudeSlimServer({
  port: 8080,
  cwd: '/workspace',
  authToken: 'mysecrettoken',
  allowedTools: ['Read', 'Write', 'Edit'],
  maxWriteSize: 1000000
});

// Start the server
const instance = server.start();

// Or use the Express app directly
const { app } = server;
app.listen(3000);

API Endpoints

GET /healthz

Health check endpoint that returns server status.

Response:

{
  "status": "healthy",
  "cwd": "/workspace",
  "tools": 7,
  "timestamp": "2024-01-01T00:00:00.000Z"
}

POST /claude

Main endpoint for Claude AI interactions using Server-Sent Events.

Request Body:

{
  "prompt": "Help me write a function to calculate fibonacci numbers",
  "options": {
    "maxTurns": 4,
    "permissionMode": "bypassPermissions"
  }
}

Response: Server-Sent Events stream

data: {"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll help you..."}]},"sessionId":"abc123","messageIndex":1}

event: complete
data: {"sessionId":"abc123","totalMessages":5,"duration":1234}

Configuration

CLI Arguments

Environment Variables

Priority: CLI arguments > Environment variables > Defaults

Available Tools

The following tools can be enabled/disabled:

• LS - List directory contents
• Glob - File pattern matching
• Grep - Search file contents
• Read - Read file contents
• Edit - Edit files
• MultiEdit - Multiple edits in one operation
• Write - Write/create files
• Bash - Execute shell commands (use with caution)

Security Features

• Path validation - Prevents access outside the working directory
• Sensitive file protection - Blocks access to .env, .ssh, keys, etc.
• Command filtering - Blocks dangerous bash commands (if Bash tool is enabled)
• Write size limits - Configurable maximum file size for write operations
• Authentication - Optional Bearer token authentication

Docker Deployment

Using Docker Compose

version: '3.8'
services:
  claude-slim:
    image: claude-slim-server
    ports:
      - "9999:9999"
    volumes:
      - ./workspace:/app
    environment:
      - CLAUDE_AUTH_TOKEN=mysecrettoken
      - CC_ALLOWED_TOOLS=Read,Write,Edit

Building from source

docker build -t claude-slim-server .
docker run -p 9999:9999 -v $(pwd):/app claude-slim-server

Example Client Code

Node.js/JavaScript

async function queryClaudeServer(prompt) {
  const response = await fetch('http://localhost:9999/claude', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer mysecrettoken'  // if auth is enabled
    },
    body: JSON.stringify({ prompt })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        console.log('Received:', data);
      }
    }
  }
}

// Use it
queryClaudeServer('Help me write a React component');

Python

import json
import requests
from sseclient import SSEClient

def query_claude_server(prompt, base_url="http://localhost:9999"):
    headers = {
        "Content-Type": "application/json",
        # "Authorization": "Bearer mysecrettoken"  # if auth is enabled
    }
    
    data = {"prompt": prompt}
    
    response = requests.post(
        f"{base_url}/claude",
        headers=headers,
        json=data,
        stream=True
    )
    
    client = SSEClient(response)
    for event in client.events():
        if event.data:
            data = json.loads(event.data)
            print(f"Received: {data}")

# Use it
query_claude_server("Help me write a Python function")

cURL

# Simple query
curl -X POST http://localhost:9999/claude \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, Claude!"}'

# With authentication
curl -X POST http://localhost:9999/claude \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mysecrettoken" \
  -d '{"prompt": "Help me write a function"}'

Development

Building from source

# Clone the repository
git clone https://github.com/yourusername/claude-slim-server.git
cd claude-slim-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run locally
npm start

Testing the package locally

# Build the package
npm run build

# Create a tarball
npm pack

# Test installation
npm install -g ./claude-slim-server-0.1.0.tgz

# Run the installed package
claude-slim-server --help

Troubleshooting

Claude CLI not found

If you see "Claude CLI not found" error, ensure @anthropic-ai/claude-code is properly installed:

npm install @anthropic-ai/claude-code

Permission denied errors

Make sure the working directory has proper permissions:

chmod -R 755 /workspace

Authentication failures

Verify your token is correctly set:

# Via environment variable
export CLAUDE_AUTH_TOKEN=mysecrettoken

# Or via CLI
claude-slim-server --auth-token mysecrettoken

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.