Installation

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:

Platform	Minimum Version
macOS	13.3+ (required for MLX support)
iOS	16.0+
watchOS	9.0+
tvOS	16.0+
visionOS	1.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

Add Package Dependency in Xcode

Open your Xcode project.
Navigate to File → Add Package Dependencies…
Enter the repository URL:

https://github.com/tryorbitai/orbit-ai-swift

Select version 1.0.0 or later.
Choose your target and click Add Package.

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")
            ]
        )
    ]
)

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

Select your target scheme (Product → Scheme → Edit Scheme…)
Go to Run → Arguments
Add environment variables under Environment Variables section

Example variables:

OPENAI_API_KEY = your-openai-api-key-here
ORBIT_LOG_LEVEL = info

Create .env File

Create a .env file in your project root:

.env

# LLM Provider API Keys
OPENAI_API_KEY=your-openai-api-key-here

# **OrbitAI** Configuration
ORBIT_LOG_LEVEL=info
ORBIT_DATABASE_PATH=./orbit_data.db
ORBIT_ENABLE_TELEMETRY=true

# Optional: Custom Settings
ORBIT_DEFAULT_MODEL=gpt-4o
ORBIT_MAX_TOKENS=4096

Never commit .env files to version control. Add .env to your .gitignore file.

Export in Terminal

For command-line applications, export variables in your shell:

export OPENAI_API_KEY="your-openai-api-key-here"
export ORBIT_LOG_LEVEL="info"

Or run your app with inline variables:

OPENAI_API_KEY="your-api-key" swift run MyApp

Configuration Variables Reference

LLM Provider API Keys

Configure API keys for different LLM providers:

Variable	Provider	Required	Example
`OPENAI_API_KEY`	OpenAI	Yes*	`your-openai-key`

At least one provider key is required.

Logging Configuration

Control logging behavior:

Variable	Description	Default	Options
`ORBIT_LOG_LEVEL`	Logging verbosity	`info`	`trace`, `debug`, `info`, `warning`, `error`
`ORBIT_LOG_FORMAT`	Log output format	`pretty`	`pretty`, `json`
`ORBIT_LOG_FILE`	Log file path	None	File path string

Database & Storage

Configure data persistence:

Variable	Description	Default
`ORBIT_DATABASE_PATH`	SQLite database location	`./orbit_data.db`
`ORBIT_MEMORY_STORAGE`	Memory storage path	`./orbit_memory/`
`ORBIT_CACHE_DIR`	Cache directory	`./orbit_cache/`

Performance & Limits

Set performance parameters:

Variable	Description	Default
`ORBIT_MAX_TOKENS`	Maximum tokens per request	`4096`
`ORBIT_TIMEOUT`	Request timeout (seconds)	`60`
`ORBIT_MAX_RETRIES`	Maximum retry attempts	`3`
`ORBIT_RATE_LIMIT`	Requests per minute	`60`

Feature Flags

Enable/disable features:

Variable	Description	Default
`ORBIT_ENABLE_TELEMETRY`	Usage analytics	`true`
`ORBIT_ENABLE_MEMORY`	Agent memory system	`true`
`ORBIT_ENABLE_GUARDRAILS`	Safety checks	`true`
`ORBIT_ENABLE_TOOLS`	Tool integration	`true`

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

Navigate to System Settings → Privacy & Security.
Select the appropriate category (e.g., “Full Disk Access”, “Automation”).
Add your application.
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

Package Resolution Fails

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+)

MLX Dependencies Error

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)

API Key Not Found

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)

Permission Denied Errors

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

Memory or Performance Issues

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

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"]

Use .gitignore

Add sensitive files to .gitignore:

.gitignore

.env
.env.local
*.db
orbit_data.db
orbit_memory/
orbit_cache/

Rotate Keys Regularly

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

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

Getting started

Core Concepts

Tools

Learn

Requirements

Swift 6.0+

Xcode 15.0+

macOS 13.3+

iOS 16.0+

Platform Support

Managed Dependencies

Swift Package Manager Installation

Environment Variables Configuration

Configure in Xcode

Create .env File

Export in Terminal

Configuration Variables Reference

macOS Security & Permissions

Required Permissions

Network Access

File System Access

Calendar & Reminders

Location Services

Granting Permissions

Verification & Testing

Troubleshooting

Security Best Practices

API Key Security

Next Steps

Quickstart Guide

Core Components

Agent Examples

API Reference

Getting started

Core Concepts

Tools

Learn

​Requirements

Swift 6.0+

Xcode 15.0+

macOS 13.3+

iOS 16.0+

​Platform Support

​Managed Dependencies

​Swift Package Manager Installation

​Environment Variables Configuration

​Configure in Xcode

​Create .env File

​Export in Terminal

​Configuration Variables Reference

​macOS Security & Permissions

​Required Permissions

Network Access

File System Access

Calendar & Reminders

Location Services

​Granting Permissions

​Verification & Testing

​Troubleshooting

​Security Best Practices

​API Key Security

​Next Steps

Quickstart Guide

Core Components

Agent Examples

API Reference

Requirements

Platform Support

Managed Dependencies

Swift Package Manager Installation

Environment Variables Configuration

Configure in Xcode

Create .env File

Export in Terminal

Configuration Variables Reference

macOS Security & Permissions

Required Permissions

Granting Permissions

Verification & Testing

Troubleshooting

Security Best Practices

API Key Security

Next Steps