Skip to main content

​
Requirements

Before installing OrbitAI, ensure your development environment meets these requirements:

Swift 6.0+

Latest Swift toolchain required

Xcode 15.0+

For iOS/macOS development

macOS 13.3+

Required for MLX support

iOS 16.0+

Minimum iOS version supported

​
Platform Support

OrbitAI supports multiple Apple platforms:
PlatformMinimum Version
macOS13.3+ (required for MLX support)
iOS16.0+
watchOS9.0+
tvOS16.0+
visionOS1.0+

​
Managed Dependencies

OrbitAI automatically manages all required dependencies:
  • GRDB.swift - SQLite persistence
  • swift-log - Structured logging
  • mlx-swift - ML embeddings and semantic search
  • SwiftSoup - HTML parsing and web scraping

​
Swift Package Manager Installation

1

Add Package Dependency in Xcode

  1. Open your Xcode project.
  2. Navigate to File → Add Package Dependencies…
  3. Enter the repository URL:
https://github.com/tryorbitai/orbit-ai-swift
  1. Select version 1.0.0 or later.
  2. Choose your target and click Add Package.
2

Or Add to Package.swift

Add OrbitAI to your Package.swift file:
Package.swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MyOrbitAIApp",
    platforms: [
        .macOS(.v13_3), // Required for MLX
        .iOS(.v16)
    ],
    dependencies: [
        .package(url: "https://github.com/tryorbitai/orbit-ai-swift.git", from: "1.0.0")
    ],
    targets: [
        .executableTarget(
            name: "MyOrbitAIApp",
            dependencies: [
                .product(name: "OrbitAI", package: "orbit-ai")
            ]
        )
    ]
)
3

Import and Initialize

Import OrbitAI in your Swift files and configure:
import OrbitAI

// Initialize OrbitAI
OrbitAI.configure()

​
Environment Variables Configuration

OrbitAI uses environment variables for API keys and configuration. Set them up using one of these methods:
  • Xcode Scheme
  • .env File
  • Command Line

​
Configure in Xcode

  1. Select your target scheme (Product → Scheme → Edit Scheme…)
  2. Go to Run → Arguments
  3. Add environment variables under Environment Variables section
Example variables:
OPENAI_API_KEY = your-openai-api-key-here
ORBIT_LOG_LEVEL = info

​
Configuration Variables Reference

Configure API keys for different LLM providers:
VariableProviderRequiredExample
OPENAI_API_KEYOpenAIYes*your-openai-key
At least one provider key is required.
Control logging behavior:
VariableDescriptionDefaultOptions
ORBIT_LOG_LEVELLogging verbosityinfotrace, debug, info, warning, error
ORBIT_LOG_FORMATLog output formatprettypretty, json
ORBIT_LOG_FILELog file pathNoneFile path string
Configure data persistence:
VariableDescriptionDefault
ORBIT_DATABASE_PATHSQLite database location./orbit_data.db
ORBIT_MEMORY_STORAGEMemory storage path./orbit_memory/
ORBIT_CACHE_DIRCache directory./orbit_cache/
Set performance parameters:
VariableDescriptionDefault
ORBIT_MAX_TOKENSMaximum tokens per request4096
ORBIT_TIMEOUTRequest timeout (seconds)60
ORBIT_MAX_RETRIESMaximum retry attempts3
ORBIT_RATE_LIMITRequests per minute60
Enable/disable features:
VariableDescriptionDefault
ORBIT_ENABLE_TELEMETRYUsage analyticstrue
ORBIT_ENABLE_MEMORYAgent memory systemtrue
ORBIT_ENABLE_GUARDRAILSSafety checkstrue
ORBIT_ENABLE_TOOLSTool integrationtrue

​
macOS Security & Permissions

OrbitAI may require specific permissions for certain features on macOS.

​
Required Permissions

Depending on the tools and features you use, you may need to grant:

Network Access

Required for LLM API calls and web scraping tools

File System Access

For knowledge base document ingestion and file operations

Calendar & Reminders

When using Apple ecosystem tools

Location Services

For location-aware agent features

​
Granting Permissions

  1. Navigate to System Settings → Privacy & Security.
  2. Select the appropriate category (e.g., “Full Disk Access”, “Automation”).
  3. Add your application.
  4. Restart your application.
You’ll be prompted for permissions when features requiring them are first accessed.

​
Verification & Testing

Verify your installation with this simple test:
Test.swift
import OrbitAI

// Configure OrbitAI
OrbitAI.configure()

// Create a simple agent
let testAgent = Agent(
    role: "Test Assistant",
    purpose: "Verify OrbitAI installation",
    context: "Simple test agent"
)

// Create and run a test task
let testTask = Task(
    description: "Say 'Hello from OrbitAI!'",
    expectedOutput: "A greeting message",
    agent: testAgent
)

let orbit = try Orbit(
    agents: [testAgent],
    tasks: [testTask],
    process: .sequential
)

let results = try await orbit.start()
print("✅ OrbitAI is working! Result: \(results.output)")
Run the test: 
swift run Test
Expected output: 
✅ OrbitAI is working! Result: Hello from OrbitAI!

​
Troubleshooting

Problem: Xcode can’t resolve the OrbitAI packageSolutions:
  • Ensure you’re using Xcode 15.0+
  • Check your internet connection
  • Try resetting package cache: File → Packages → Reset Package Caches
  • Verify the repository URL is correct
  • Check if the minimum platform version is met (macOS 13.3+)
Problem: MLX-related build errorsSolutions:
  • Verify you’re running on macOS 13.3 or later
  • MLX requires Apple Silicon (M1/M2/M3) or compatible Intel Mac
  • Ensure Xcode Command Line Tools are installed: xcode-select --install
  • Try cleaning build folder: Product → Clean Build Folder (Shift + Cmd + K)
Problem: “Missing API key” error at runtimeSolutions:
  • Verify environment variables are set correctly
  • Check spelling of variable names (e.g., OPENAI_API_KEY)
  • Ensure .env file is in the correct directory
  • For Xcode: Confirm environment variables are set in scheme settings
  • Print environment variables to debug: print(ProcessInfo.processInfo.environment)
Problem: macOS blocks file or network accessSolutions:
  • Grant necessary permissions in System Settings → Privacy & Security
  • For file access: Add app to “Full Disk Access” or “Files and Folders”
  • For network: Check “Network” permissions
  • Restart your app after granting permissions
Problem: High memory usage or slow performanceSolutions:
  • Adjust ORBIT_MAX_TOKENS to a lower value
  • Disable memory features if not needed: ORBIT_ENABLE_MEMORY=false
  • Clear cache directory periodically
  • Monitor agent execution with logging: ORBIT_LOG_LEVEL=debug
  • Consider using lighter LLM models for development

​
Security Best Practices

Protect your API keys and sensitive data.

​
API Key Security

1

Never Hardcode Keys

❌ Don’t do this:
let apiKey = "hardcoded-api-key-here" // Bad!
✅ Do this instead:
let apiKey = ProcessInfo.processInfo.environment["OPENAI_API_KEY"]
2

Use .gitignore

Add sensitive files to .gitignore:
.gitignore
.env
.env.local
*.db
orbit_data.db
orbit_memory/
orbit_cache/
3

Rotate Keys Regularly

  • Regenerate API keys periodically
  • Use different keys for development and production
  • Revoke compromised keys immediately
4

Implement Access Controls

// Use key management services
import Security

// Store keys in Keychain instead of environment
func getAPIKey() -> String? {
    // Retrieve from Keychain
    return KeychainManager.retrieve(key: "openai_api_key")
}

​
Next Steps

Quickstart Guide

Build your first OrbitAI application

Core Components

Learn about Agents, Tasks, and Orbits

Agent Examples

Explore practical agent implementations

API Reference

Detailed API documentation