solstice-agent 0.2.10

Local-first AI agent with tools, memory, messaging gateway support, and optional provider extras.

Sol

The open-source AI agent that lives on your computer.

Talk to it. It reads files, uses the browser, runs commands, remembers context, and works across your apps.

No forced cloud account. Your machine. Your data. Your agent.

---

Quick Install

Pick the provider path you actually want:

Base package + Ollama:

pipx install solstice-agent

OpenAI:

pipx install 'solstice-agent[openai]'

Anthropic:

pipx install 'solstice-agent[anthropic]'

Gemini:

pipx install 'solstice-agent[gemini]'

If you want the one-line installers, they install the OpenAI extra by default.

Windows (PowerShell):

irm https://raw.githubusercontent.com/Solasticeaistudio/solstice-agent/main/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/Solasticeaistudio/solstice-agent/main/install.sh | bash

Then:

sol --setup
sol

For gateway deployments, set an explicit workspace root:

sol-gateway --profile gateway --workspace-root /absolute/path/to/workspace

Legacy aliases still work:

solstice-agent
solstice-gateway

What It Feels Like

> Summarize this repo and tell me how it works
> Check my calendar every morning and message me the summary
> Open this API and figure out what auth it uses
> Remember that I deploy production on Fridays
> Hey Sol, what's on my screen?

Sol is not a chatbot wrapper. It is an installable agent with real tools, persistent memory, voice, scheduling, browser control, and local-first guardrails.

Why Sol

• Runs on normal computers
• Open source and MIT licensed
• Local-first by default
• Works with OpenAI, Anthropic, Gemini, or Ollama when the matching provider path is installed
• Uses real tools instead of pretending
• Same agent across terminal, desktop, and messaging channels

What It Can Do

Sol ships with built-in tools across files, browser, terminal, web, API discovery, voice, screen capture, recording, Docker sandboxing, SSH remote execution, Singularity/Apptainer HPC containers, Modal serverless compute, scheduling, self-improving skills, memory, cross-channel messaging, background sub-agents, and workflow orchestration.

It also supports external connectors installed into the same Python environment. That interface stays public, while deep Artemis integrations can ship as separate packages. Connector loading and boundary details live in docs/CONNECTORS.md.

What that means in practice:

• Read, write, patch, and search files on your machine
• Run commands, background jobs, and inspect logs
• Search the web and open pages in a real browser
• Inspect unfamiliar APIs and map their endpoints
• SSH into remote servers and run commands, transfer files, manage sessions
• Run Singularity/Apptainer containers on HPC clusters where Docker isn't an option
• Offload heavy compute to Modal — ephemeral GPU jobs or persistent scheduled apps
• Remember facts and resume conversations across sessions
• Synthesize reusable skill guides from completed tasks and improve them over time
• Listen for a wake word and reply by voice
• Schedule recurring work while you are away
• Respond through messaging platforms using the same memory and personality
• Run background sub-agents with task tracking, live progress, and resumable state
• Submit workflow DAGs, mutate queued nodes, stream workflow events, and export snapshots

The Main Hook

Most agent projects feel like hosted wrappers around an LLM.

Sol feels different because it lives where your work lives:

• your filesystem
• your terminal
• your browser
• your notifications
• your chats

That is the product.

Local-First by Default

Sol can run with:

• OpenAI
• Anthropic
• Gemini
• Ollama for fully local inference

Use cloud models if you want. Use local models if you want. The product is not tied to one provider or one hosted account.

# OpenAI
export OPENAI_API_KEY=sk-...
sol

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
sol --provider anthropic

# Google Gemini
export GEMINI_API_KEY=AI...
sol --provider gemini

# Ollama (fully local)
sol --provider ollama --model llama3.1

Reach It From Anywhere

Sol can expose the same agent across messaging channels. Message it on Telegram, Discord, Slack, email, or other supported gateways and keep the same memory and personality.

Example:

export GATEWAY_TELEGRAM_ENABLED=true
export GATEWAY_TELEGRAM_BOT_TOKEN=your-token
sol-gateway

For Outlook/Graph email channels, Sol can use either a direct GATEWAY_EMAIL_GRAPH_TOKEN or a shared MSAL cache file via GATEWAY_EMAIL_GRAPH_CACHE_PATH.

Talk to It by Voice

Say "hey Sol" and start talking. Sol can listen through your microphone, maintain a live transcript, and respond out loud. You can also switch voices, use push-to-talk, or disable voice entirely.

It Remembers

Sol stores conversation history and facts across sessions.

sol --continue

Example:

> Remember that my preferred language is Python
> What's my preferred language?
Python.

Schedule Work

Sol can run recurring tasks even when you are not actively chatting with it.

sol --cron "every day at 9am" "summarize my calendar"

You can also just ask:

> Schedule a daily summary of my GitHub notifications at 9am

Docs

• Security: docs/SECURITY.md
• Connectors: docs/CONNECTORS.md
• User guide: docs/USER_GUIDE.md
• Roadmap / todo: docs/TODO.md
• Camunda quickstart: docs/WINDOWS_CAMUNDA_QUICKSTART.md
• Camunda demo script: docs/CAMUNDA_DEMO_SCRIPT.md

Workflow Orchestration

Sol now has first-class orchestration for delegated work:

• async sub-agents with resumable runs
• persistent task and workflow state
• dependency-aware workflow DAGs
• workflow mutation for node add, disable, enable, remove, retry, and edge rewiring
• live sub-agent and workflow event streams
• workflow snapshots and JSON export for auditability

The next planned step is workflow replay and cloning from an exported spec or saved snapshot. That item is tracked in docs/TODO.md.

Install Options

If you prefer the cleanest CLI install:

pipx install solstice-agent

Provider extras:

pipx install 'solstice-agent[openai]'
pipx install 'solstice-agent[anthropic]'
pipx install 'solstice-agent[gemini]'

If you prefer manual install:

pip install 'solstice-agent[all]'

Or install only what you need:

pip install solstice-agent
pip install 'solstice-agent[openai]'
pip install 'solstice-agent[anthropic]'
pip install 'solstice-agent[gemini]'
pip install 'solstice-agent[voice]'
pip install 'solstice-agent[browser]'
pip install 'solstice-agent[gateway]'
pip install 'solstice-agent[screen]'
pip install 'solstice-agent[recording]'
pip install 'solstice-agent[docker]'

Browser support requires:

playwright install chromium

Security

Sol is intentionally powerful, so the safety story matters.

• Runtime profiles make tool defaults explicit: local_safe, developer, gateway, power_user
• Network requests are checked for SSRF and blocked from private/internal targets
• Gateway file operations fail closed unless workspace_root is configured
• File operations are sandboxed to the workspace and sensitive paths are blocked
• Dangerous terminal commands require explicit confirmation
• Browser execution is constrained
• Docker sandbox jobs run without network and without privilege escalation
• Gateway server binds to localhost by default and uses token auth when exposed

Security validation is centralized in solstice_agent/tools/security.py for auditing.

Dedicated security guide: docs/SECURITY.md

Architecture

solstice_agent/
  agent/
    core.py
    memory.py
    scheduler.py
    router.py
    providers/
  tools/
    file_ops.py
    terminal.py
    web.py
    blackbox.py
    browser.py
    voice.py
    screen.py
    recording.py
    docker_sandbox.py
    security.py
  gateway/
    manager.py
    channels/
  cli.py
  server.py

At the center is a tool-calling loop. User message in, model decides whether to use tools, tools execute, results come back, final answer returns.

Roadmap

• Community skill marketplace
• OpenRouter provider
• MCP client support
• Agent-to-agent delegation
• Stable public API

Contributing

git clone https://github.com/Solasticeaistudio/solstice-agent
cd solstice-agent
pip install -e ".[dev,all]"
pytest

License

MIT.

Built by Solstice Studio.