Skip to content

SETUP.md

Latest commit

 

History

History
343 lines (247 loc) · 7.12 KB

SETUP.md

File metadata and controls

343 lines (247 loc) · 7.12 KB

ArnOS Setup Guide

Complete setup instructions for desktop and mobile/web usage.

Prerequisites

  • PostgreSQL 14+ (any provider: Supabase, Neon, Railway, local, etc.)
  • Node.js 18+
  • Claude Code or Claude Desktop (for local use) OR server hosting (for mobile/web)

Part 1: Database Setup

Create PostgreSQL Database

Choose any PostgreSQL provider:

Option A: Supabase (recommended for beginners)

  1. Go to supabase.com
  2. Create account and new project
  3. Go to Settings → Database
  4. Copy the "Pooler" connection string

Option B: Neon

  1. Go to neon.tech
  2. Create project
  3. Copy connection string

Option C: Local PostgreSQL

createdb arnos
# Connection string: postgresql://localhost:5432/arnos

Create Schema

  1. Download the schema:
# See DATABASE.md for full schema
# Or create a schema.sql file with all CREATE TABLE statements
  1. Run the schema:
psql YOUR_DATABASE_URL < schema.sql

Part 2: Application Setup

Clone and Install

git clone https://github.com/yourusername/arnos.git
cd arnos
npm install

Configure Environment

cp .env.example .env

Edit .env with your settings:

# Server
PORT=3456
SERVER_URL=http://localhost:3456  # Change when deployed

# Database
DATABASE_URL=postgresql://user:password@host:port/database

# OAuth (only needed for mobile/web)
# Skip this section if using desktop only

Part 3A: Local Setup (Claude Code / Claude Desktop)

For Claude Code or Claude Desktop on your computer.

1. Build the Project

npm run build

2. Configure Claude

For Claude Code (recommended):

Run in your project directory:

claude mcp add arnos

Then edit the generated config:

  • Mac/Linux: ~/.config/claude-code/.mcp.json
  • Windows: %APPDATA%\claude-code\.mcp.json

For Claude Desktop:

Edit your Claude Desktop config file:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Config for both (JSON):

{
  "mcpServers": {
    "arnos": {
      "command": "node",
      "args": ["/absolute/path/to/arnos/dist/index.js"],
      "env": {
        "DATABASE_URL": "your-database-connection-string",
        "PORT": "3456"
      }
    }
  }
}

Important: Use absolute paths, not relative paths.

3. Restart Claude

Close and reopen Claude Code or Claude Desktop. ArnOS tools should now appear.

4. Test It

Try:

"What's on my plate today?"

Part 3B: Mobile/Web Setup (Hosted)

For Claude mobile app or Claude.ai web.

1. Generate OAuth Credentials

# Generate client ID (any random string)
echo "arnos-$(openssl rand -hex 8)"

# Generate client secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Generate session secret
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Generate password hash (replace 'your-password' with your actual password)
node -e "const bcrypt = require('bcrypt'); bcrypt.hash('your-password', 10, (e,h) => console.log(h))"

Add these to your .env:

OAUTH_CLIENT_ID=arnos-your-generated-id
OAUTH_CLIENT_SECRET=your-generated-secret
OAUTH_PASSWORD_HASH=your-bcrypt-hash
SESSION_SECRET=your-session-secret

2. Deploy to Server

Choose any Node.js hosting:

Option A: Railway

# Install Railway CLI
npm i -g @railway/cli

# Login
railway login

# Create project
railway init

# Add environment variables in Railway dashboard
# Deploy
railway up

Option B: Render

  1. Connect GitHub repo
  2. Create Web Service
  3. Build command: npm run build
  4. Start command: npm start
  5. Add environment variables

Option C: Fly.io

fly launch
fly deploy

Option D: Your VPS

# Build
npm run build

# Run with PM2
pm2 start dist/index.js --name arnos

# Or with systemd
# Create /etc/systemd/system/arnos.service

3. Get Your Server URL

After deployment, note your server URL (e.g., https://your-app.railway.app)

Update .env on server:

SERVER_URL=https://your-actual-deployment-url.com

4. Configure Claude Web (syncs to mobile)

Important: Configure via Claude.ai web - it will sync to mobile automatically.

  1. Open Claude.ai in your browser
  2. Go to Settings → Custom Connectors
  3. Click "Add custom connector"
  4. Enter:
    • Name: ArnOS
    • URL: https://your-server-url.com/mcp
  5. Click "Advanced settings"
  6. Enter your OAuth credentials:
    • Client ID: (from .env)
    • Client Secret: (from .env)
  7. Click "Add"
  8. You'll be redirected to password form
  9. Enter the password you used to generate the bcrypt hash
  10. Done! Tools appear in web and sync to mobile app automatically

Troubleshooting

Desktop: "Command not found"

  • Check absolute path in config
  • Ensure npm run build completed successfully
  • Try running node /path/to/dist/index.js manually to see errors

Desktop: "Database connection failed"

  • Verify DATABASE_URL is correct
  • Test connection: psql YOUR_DATABASE_URL
  • Check database is accessible from your machine

Mobile/Web: "OAuth error"

  • Verify all OAuth credentials in .env match
  • Check SERVER_URL is set to your actual deployment URL
  • Ensure password hash was generated correctly

Mobile/Web: "Password incorrect"

  • Regenerate password hash with correct password
  • Update OAUTH_PASSWORD_HASH in .env
  • Redeploy

General: "Module not found"

  • Run npm install again
  • Delete node_modules and package-lock.json, then npm install

Updating

Local (Claude Code / Desktop)

cd arnos
git pull
npm install
npm run build
# Restart Claude Code or Claude Desktop

Mobile/Web

git pull
npm install
npm run build
# Redeploy to your hosting provider

Security Notes

  • Never commit your .env file
  • Use strong passwords for OAuth
  • Rotate credentials periodically
  • Backup your database regularly

Using With Other MCPs

ArnOS works alongside other MCP servers. Install them separately in Claude:

Readwise MCP

  • Use the Readwise MCP Enhanced
  • Access your complete Readwise library (Reader documents + Highlights)
  • Search, fetch, and extract content → Save as learnings in ArnOS
  • Example: "Search Readwise for AI agents" → "Save these insights as learnings"

Google Calendar MCP

  • Use Claude's built-in Google Calendar MCP
  • Check your schedule → Reference in ArnOS journal

X (Twitter) MCP

  • Use the X MCP server
  • Generate content from ArnOS learnings → Post tweets and threads via X MCP

Each MCP is focused. They work together in Claude.

Next Steps

  • Read DATABASE.md for schema details
  • Check README.md for usage examples
  • Join discussions for help and use cases

Need Help?

  • Issues: Report bugs on GitHub
  • Discussions: Ask questions, share use cases
  • Discord: (Coming soon)