Build From Terminal

This guide covers the direct local workflow for building and running Sloppy without Docker.

Supported environments

Platform	Status	Notes
macOS 14+	Supported	Primary local development environment
Linux	Supported	CI runs on Ubuntu with Swift 6.2 and libsqlite3-dev

Prerequisites

Swift runtime

• Swift 6 toolchain
• sqlite3 runtime available on the machine

Dashboard runtime

• Node.js
• npm

Linux packages

On Ubuntu or Debian-based systems, install the SQLite development headers before building:

sudo apt-get update
sudo apt-get install -y libsqlite3-dev

Resolve dependencies

From the repository root:

swift package resolve

Build the Swift targets

Development build:

swift build

Release builds:

swift build -c release --product Core
swift build -c release --product Node
swift build -c release --product App

Run the Swift targets

Start the core runtime:

swift run Core

Useful runtime variants:

swift run Core --oneshot
swift run Core --run-demo-request
swift run Core --config-path sloppy.json

Run the other executables when needed:

swift run Node
swift run App

Run the Swift tests

Full suite:

swift test --parallel

Run a single test or group:

swift test --filter CoreTests.postChannelMessageEndpoint
swift test --filter CoreTests
swift test --filter AgentRuntimeTests

List tests:

swift test list

Run the dashboard

From Dashboard/:

npm install
npm run dev

Production build:

npm run build

Preview the production bundle:

npm run preview

Typical local development loop

1. Start Core from the repository root with swift run Core.
2. Start the dashboard from Dashboard/ with npm run dev.
3. Make a focused code change.
4. Run the smallest relevant verification first.
5. Before opening a PR, run the CI-parity checks listed below.

CI-parity checks

These are the commands the repository expects contributors to keep green:

swift test --parallel
swift build -c release --product Core
swift build -c release --product Node
swift build -c release --product App
cd Dashboard
npm install
npm run build

Notes

• On first swift run Core, Sloppy can create a workspace layout and a default sloppy.json.
• The generated config includes visor.scheduler.enabled, visor.scheduler.intervalSeconds, visor.scheduler.jitterSeconds, and visor.bootstrapBulletin.
• Model providers use environment variables for API keys when no key is set in config. See the Model Providers guide for details.
• Ollama uses the local endpoint by default and requires no API key.

Environment variables

Variable	Purpose
OPENAI_API_KEY	OpenAI model provider
GEMINI_API_KEY	Google Gemini model provider
ANTHROPIC_API_KEY	Anthropic Claude model provider
BRAVE_API_KEY	Brave web search tool
PERPLEXITY_API_KEY	Perplexity web search tool

Environment values take precedence over empty sloppy.json keys but are overridden when a config key is explicitly set.