Deployment

NeuralCleave runs anywhere Python 3.10+ is available. For server deployments, a Dockerfile and docker-compose.yml are included. One-click deploy buttons are provided for Railway and Render.

Docker

bash

# Build the image
docker build -t neuralcleave:latest .

# Run with config mounted from host
docker run -d \
  --name neuralcleave \
  -p 7432:7432 \
  -v ~/.neuralcleave:/root/.neuralcleave \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e TELEGRAM_BOT_TOKEN=$TELEGRAM_BOT_TOKEN \
  neuralcleave:latest

💡

Mount ~/.neuralcleave to persist config and the SQLite memory database across container restarts. Without the mount, memory is wiped on each restart.

docker-compose

The included docker-compose.yml starts NeuralCleave, Redis, and Qdrant together:

yaml

version: "3.9"
services:
  neuralcleave:
    build: .
    ports:
      - "7432:7432"
    volumes:
      - ./config:/root/.neuralcleave
    env_file: .env
    depends_on:
      - redis
      - qdrant
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant_data:/qdrant/storage
    restart: unless-stopped

volumes:
  redis_data:
  qdrant_data:

bash

docker compose up -d

Railway

Railway detects the Dockerfile automatically. Set the following environment variables in the Railway project settings:

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Primary LLM provider key
`GATEWAY_HOST`	Yes	Set to `0.0.0.0`
`GATEWAY_PORT`	Yes	Set to `7432`
`REDIS_URL`	Recommended	Add Railway Redis plugin
`QDRANT_URL`	Optional	External Qdrant Cloud or self-hosted

The gateway binds to 0.0.0.0:7432. Railway routes HTTPS traffic to it automatically.

Render

Use the Web Service type on Render. Set the runtime to Docker and configure the same environment variables. Render assigns a public HTTPS URL and handles TLS termination.

yaml

# render.yaml (optional, Infrastructure-as-Code)
services:
  - type: web
    name: neuralcleave
    runtime: docker
    plan: starter
    envVars:
      - key: ANTHROPIC_API_KEY
        sync: false
      - key: GATEWAY_HOST
        value: 0.0.0.0
      - key: GATEWAY_PORT
        value: "7432"

neuralcleave cloud CLI

The neuralcleave cloud subcommand manages remote deployments from the local terminal:

bash

# Authenticate
neuralcleave cloud login

# Deploy the current config to the cloud
neuralcleave cloud deploy

# Stream live logs from the cloud instance
neuralcleave cloud logs --follow

# Check cloud instance status
neuralcleave cloud status

# Sync local config to cloud without restarting
neuralcleave cloud sync-config

# Restart the cloud instance
neuralcleave cloud restart

Environment file

For both local and server deployments, put secrets in a .env file alongside config.toml. The config uses ENV: references to read from it at startup:

bash

# ~/.neuralcleave/.env — never commit this file
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=1234567890:ABC...
DISCORD_BOT_TOKEN=MTk4NjIy...
ELEVENLABS_API_KEY=el-...

Health check

Configure container orchestrators and load balancers to probe GET /health. It returns HTTP 200 immediately with no auth required:

bash

curl http://localhost:7432/health
# → {"status":"ok","version":"2.1.0","agent":"NeuralCleave"}