CIRIS Standalone Installation

Get CIRIS Agent + GUI running in minutes without Docker.

Quick Start

curl -sSL https://ciris.ai/install.sh | bash

That's it! The installer will:

✅ Install all dependencies (Python 3.9+, Node.js 20+, pnpm)
✅ Clone CIRISAgent and CIRISGUI repositories
✅ Set up Python virtual environment
✅ Install all packages
✅ Generate secure encryption keys
✅ Create systemd/launchd services (optional)
✅ Provide helper scripts for start/stop/status

What You Get

After installation, you'll have:

~/ciris/
├── CIRISAgent/          # Agent backend (Python)
├── CIRISGUI/            # Web UI (Next.js)
├── .env                 # Configuration file
├── scripts/
│   ├── start.sh         # Start both services
│   ├── stop.sh          # Stop both services
│   └── status.sh        # Check service status
└── logs/                # Service logs (if using systemd/launchd)

Installation Options

Custom Installation Directory

curl -sSL https://ciris.ai/install.sh | bash -s -- --install-dir /opt/ciris

Skip Service Installation

curl -sSL https://ciris.ai/install.sh | bash -s -- --skip-service

Development Mode

Installs development dependencies and builds in dev mode:

curl -sSL https://ciris.ai/install.sh | bash -s -- --dev

Install Specific Branches

curl -sSL https://ciris.ai/install.sh | bash -s -- --agent-branch release/1.6.2 --gui-branch develop

Environment Variables

You can also configure via environment variables:

export CIRIS_INSTALL_DIR="/opt/ciris"
export CIRIS_AGENT_PORT="8080"
export CIRIS_GUI_PORT="3000"
curl -sSL https://ciris.ai/install.sh | bash

Post-Installation

1. LLM Configuration

The installer prompts you to choose between OpenAI or a local/custom LLM:

Option 1: OpenAI (Default)

Enter your OpenAI API key when prompted
Or edit ~/ciris/.env later and set OPENAI_API_KEY

Option 2: Local/Custom LLM (Ollama, LM Studio, etc.) During installation, you'll be prompted for:

Base URL (default: http://localhost:11434 for Ollama)
Model name (e.g., llama3, mistral, codellama)
API key (default: local if no authentication required)

The installer will configure ~/ciris/.env automatically with:

OPENAI_API_KEY="local"
OPENAI_API_BASE="http://localhost:11434"
OPENAI_MODEL="llama3"

Popular Local LLM Servers:

Ollama: http://localhost:11434 (recommended)
LM Studio: http://localhost:1234/v1
vLLM: http://localhost:8000/v1
LocalAI: http://localhost:8080/v1

To change LLM provider later:

Edit ~/ciris/.env:

nano ~/ciris/.env

2. Start CIRIS

Option A: As a Service (Linux with systemd)

systemctl --user start ciris-agent ciris-gui
systemctl --user enable ciris-agent ciris-gui  # Start on boot
systemctl --user status ciris-agent ciris-gui  # Check status

Option B: As a Service (macOS with launchd)

Services start automatically after installation. To check:

launchctl list | grep ciris

Option C: Manual Start

~/ciris/scripts/start.sh

Press Ctrl+C to stop.

3. Open the Web UI

Open your browser to: http://localhost:3000

Credentials: Set during setup wizard on first run

The agent API is available at: http://localhost:8080

Management Commands

Check Status

~/ciris/scripts/status.sh

Stop Services

Systemd:

systemctl --user stop ciris-agent ciris-gui

Launchd:

launchctl unload ~/Library/LaunchAgents/ai.ciris.agent.plist
launchctl unload ~/Library/LaunchAgents/ai.ciris.gui.plist

Manual:

~/ciris/scripts/stop.sh

View Logs

Systemd:

journalctl --user -u ciris-agent -f
journalctl --user -u ciris-gui -f

Launchd:

tail -f ~/ciris/logs/agent.log
tail -f ~/ciris/logs/gui.log

Manual:

tail -f ~/ciris/CIRISAgent/logs/latest.log

Update CIRIS

cd ~/ciris/CIRISAgent
git pull origin main
source venv/bin/activate
pip install -r requirements.txt

cd ~/ciris/CIRISGUI
git pull origin main
pnpm install
cd apps/agui && pnpm build

# Restart services
systemctl --user restart ciris-agent ciris-gui

Uninstallation

curl -sSL https://ciris.ai/install.sh | bash -s -- --uninstall

Or manually:

# Stop services
systemctl --user stop ciris-agent ciris-gui
systemctl --user disable ciris-agent ciris-gui
rm ~/.config/systemd/user/ciris-*.service

# Remove installation
rm -rf ~/ciris

Supported Platforms

Platform	Support	Init System	Package Manager
Ubuntu 20.04+	✅ Full	systemd	apt
Debian 11+	✅ Full	systemd	apt
Fedora 36+	✅ Full	systemd	dnf
CentOS 8+	✅ Full	systemd	dnf/yum
Arch Linux	✅ Full	systemd	pacman
macOS 11+	✅ Full	launchd	brew
WSL2 (Ubuntu)	✅ Full	systemd	apt
Windows (native)	⚠️ Manual	-	-

Troubleshooting

Dependencies Installation Failed

Issue: Installer cannot install Python/Node automatically

Solution: Install manually:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv nodejs npm

# macOS
brew install python@3.12 node@20

# Then run installer with --skip-deps
curl -sSL https://ciris.ai/install.sh | bash -s -- --skip-deps

Port Already in Use

Issue: Port 8080 or 3000 already in use

Solution: Configure different ports:

export CIRIS_AGENT_PORT="8081"
export CIRIS_GUI_PORT="3001"
curl -sSL https://ciris.ai/install.sh | bash

Or edit ~/ciris/.env after installation.

Services Won't Start

Issue: systemd/launchd services fail to start

Solution: Check logs:

# Systemd
journalctl --user -u ciris-agent -n 50

# Launchd
tail -50 ~/ciris/logs/agent.err.log

# Or start manually to see errors
~/ciris/scripts/start.sh

GUI Cannot Connect to Agent

Issue: Web UI shows "Cannot connect to agent"

Solution:

Check agent is running: curl http://localhost:8080/v1/status
Check .env has correct NEXT_PUBLIC_API_BASE_URL
Check firewall isn't blocking localhost connections

Python Version Too Old

Issue: Python 3.9+ required

Solution:

# Ubuntu: Use deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12 python3.12-venv

# macOS
brew install python@3.12

# Then re-run installer

Manual Installation

If you prefer not to use the installer script:

1. Install Dependencies

# Ubuntu/Debian
sudo apt-get install python3 python3-pip python3-venv nodejs npm git curl

# macOS
brew install python@3.12 node@20 git

# Install pnpm
npm install -g pnpm

2. Clone Repositories

mkdir -p ~/ciris
cd ~/ciris
git clone https://github.com/CIRISAI/CIRISAgent.git
git clone https://github.com/CIRISAI/CIRISGUI.git

3. Setup CIRISAgent

cd ~/ciris/CIRISAgent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. Setup CIRISGUI

cd ~/ciris/CIRISGUI
pnpm install
cd apps/agui
pnpm build

5. Configure Environment

cd ~/ciris
cat > .env << 'EOF'
OPENAI_API_KEY="your_api_key_here"
SECRETS_MASTER_KEY="$(openssl rand -base64 32)"
TELEMETRY_ENCRYPTION_KEY="$(openssl rand -base64 32)"
LOG_LEVEL="INFO"
CIRIS_AGENT_PORT=8080
NEXT_PUBLIC_API_BASE_URL="http://localhost:8080"
EOF

6. Start Services

Terminal 1 - Agent:

cd ~/ciris/CIRISAgent
source venv/bin/activate
source ../.env
python main.py --adapter api --port 8080

Terminal 2 - GUI:

cd ~/ciris/CIRISGUI/apps/agui
source ../../.env
pnpm start --port 3000

Advanced Configuration

PostgreSQL Backend

By default, CIRIS uses SQLite. For production, configure PostgreSQL:

Install PostgreSQL:

# Ubuntu
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql@15

Create database:

sudo -u postgres psql
CREATE DATABASE ciris_db;
CREATE USER ciris_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE ciris_db TO ciris_user;
\q

Configure in ~/ciris/.env:

CIRIS_DB_URL="postgresql://ciris_user:your_password@localhost:5432/ciris_db"

Discord Integration

Create Discord bot at https://discord.com/developers/applications

Add bot token to ~/ciris/.env:

DISCORD_BOT_TOKEN="your_bot_token"
DISCORD_CHANNEL_ID="your_channel_id"

Start with Discord adapter:

cd ~/ciris/CIRISAgent
source venv/bin/activate
python main.py --adapter discord

Reddit Integration

Create Reddit app at https://www.reddit.com/prefs/apps

Add credentials to ~/ciris/.env:

CIRIS_REDDIT_CLIENT_ID="your_client_id"
CIRIS_REDDIT_CLIENT_SECRET="your_client_secret"
CIRIS_REDDIT_USERNAME="your_username"
CIRIS_REDDIT_PASSWORD="your_password"

Start with Reddit adapter:

python main.py --adapter api --adapter reddit

Using Ollama (Local LLM)

Quick Start with Ollama:

Install Ollama (if not already installed):

# Linux/macOS
curl https://ollama.ai/install.sh | sh

# Or download from https://ollama.ai

Pull a model:

# Recommended models for CIRIS:
ollama pull llama3        # Fast, good quality (4.7GB)
ollama pull mistral       # Fast, efficient (4.1GB)
ollama pull codellama     # Good for coding tasks (3.8GB)
ollama pull llama3:70b    # Best quality, slower (39GB)

Start Ollama server:

ollama serve
# Runs on http://localhost:11434 by default

During CIRIS installation, choose:
- Provider: local
- Base URL: http://localhost:11434 (default)
- Model: llama3 (or your chosen model)
- API Key: local (default)

Test it works:

curl http://localhost:11434/api/generate -d '{
  "model": "llama3",
  "prompt": "Hello!"
}'

Switching models after installation:

Edit ~/ciris/.env and change OPENAI_MODEL:

OPENAI_MODEL="mistral"  # or llama3, codellama, etc.

Then restart CIRIS.

Getting Help

Documentation: https://github.com/CIRISAI/CIRISAgent/blob/main/docs/README.md
GitHub Issues: https://github.com/CIRISAI/CIRISAgent/issues
Community: Discord (link in README)

Next Steps

✅ Quick Start Guide - Learn the basics
✅ API Reference - REST API documentation
✅ Architecture Overview - System design
✅ Developer Guide - Contributing and extending

CIRIS: Core Identity, Integrity, Resilience, Incompleteness, and Signalling Gratitude

Ethical AI with human oversight, complete transparency, and deployment reliability.

FilesExpand file tree

STANDALONE_INSTALL.md

Latest commit

History