Skip to main content

Quickstart Guide

Get your first AI agent running on RavenmaskOS in under 10 minutes.

Prerequisites​

Before you begin, ensure you have:

  • Docker and Docker Compose installed
  • Access to an OpenAI API key (or other LLM provider)
  • Basic familiarity with command line tools
  • Minimum 8GB RAM available for services

Installation​

1. Clone the Repository​

git clone https://gitlab.ravenhelm.dev/ravenmask/ravenmaskos.git
cd ravenmaskos

2. Configure Environment​

Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env and set the following required variables:

# LLM Configuration
OPENAI_API_KEY=sk-...

# Database Configuration
POSTGRES_PASSWORD=your_secure_password
NEO4J_PASSWORD=your_secure_password

# Platform Configuration
PLATFORM_DOMAIN=localhost
PLATFORM_PORT=3000

3. Start Core Services​

Launch the platform services using Docker Compose:

docker-compose up -d

This starts:

  • PostgreSQL (source of truth database)
  • Neo4j (graph memory)
  • Redis (caching)
  • NATS JetStream (event streaming)
  • Traefik (reverse proxy)

4. Verify Installation​

Check that all services are running:

docker-compose ps

All services should show status Up and be healthy.

Create Your First Agent​

1. Access Norns Studio​

Open your browser to http://localhost:3000 (or your configured domain).

You'll see the Norns Studio interface - the low-code builder for AI agents.

2. Create a New Agent​

  1. Click "New Agent" in the top right
  2. Name your agent (e.g., "Task Helper")
  3. Select a template or start blank

3. Configure the Agent​

Basic Settings:

  • Name: Task Helper
  • Description: Helps manage and track tasks
  • LLM Model: gpt-4o-mini
  • Temperature: 0.7

System Prompt:

You are a helpful task management assistant. You help users:
- Create and organize tasks
- Set priorities and deadlines
- Track progress
- Provide reminders

Be concise and actionable in your responses.

4. Add Tools​

Click "Add Tool" and select from available integrations:

  • Linear: For project management integration
  • Notion: For note-taking
  • Slack: For notifications

Configure tool permissions and authentication as needed.

5. Deploy the Agent​

  1. Click "Test" to try your agent in the playground
  2. When satisfied, click "Deploy"
  3. Your agent is now live and accessible via API

Test Your Agent​

Via Studio Playground​

Use the built-in playground to test:

You: Create a task to review the Q4 roadmap
Agent: I've created a new task "Review Q4 Roadmap" with high priority. Would you like me to set a due date?

Via API​

Get your agent's API endpoint from the Studio dashboard:

curl -X POST https://api.ravenhelm.dev/agents/YOUR_AGENT_ID/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a task to review the Q4 roadmap"
  }'

Via n8n Workflow​

Integrate your agent into an n8n workflow:

  1. Open n8n at https://n8n.ravenhelm.dev
  2. Add a "RavenmaskOS Agent" node
  3. Select your agent from the dropdown
  4. Connect to your workflow triggers

Next Steps​

Now that you have a working agent, explore:

Troubleshooting​

Services Won't Start​

Check Docker logs:

docker-compose logs <service-name>

Common issues:

  • Port conflicts (check ports 5432, 7687, 4222 are available)
  • Insufficient memory (increase Docker memory limit)
  • Missing environment variables (verify .env file)

Agent Not Responding​

  1. Check agent status in Studio dashboard
  2. Verify LLM API key is valid
  3. Check Langfuse traces for error details
  4. Review agent logs in the platform logs view

Need Help?​