Getting Started

Documentation

Everything you need to get Polaris Agent up and running. Install, configure, and start chatting in under two minutes.

Installation

Polaris ships as a single Go binary. The easiest way to install it is via the install script: 

curl -fsSL https://raw.githubusercontent.com/berkaycubuk/polaris-agent/main/scripts/install.sh | sh

This downloads the latest release for your platform and places it in /usr/local/bin. Alternatively, you can download the binary directly from the releases page.

Requirements

  • Docker — the agent runs inside a container
  • Docker Compose — for managing the container lifecycle
  • An OpenAI-compatible API key — from OpenAI, Ollama, or any compatible provider

Configuration

Run the interactive setup wizard to create your configuration: 

polaris setup

The wizard will ask for:

  • LLM provider endpoint — the base URL for your OpenAI-compatible API
  • API key — your authentication token
  • Model name — e.g. gpt-4o, llama3, etc.
  • Telegram token (optional) — if you want Telegram integration

Configuration is stored in .env inside your data directory. You can edit it manually at any time.

Running the Agent

Start the agent with Docker Compose: 

docker compose up -d

This pulls the container image, mounts your data directory as a persistent volume, and starts the agent. Once running, you can interact with it through:

  • CLI — polaris chat
  • HTTP — localhost:8080/chat
  • Telegram — message your bot directly

To stop the agent: 

docker compose down
Core Concepts

Understanding how Polaris works

Polaris is built around a simple model: a single data directory, a Markdown wiki, and a tool loop that reads and writes both.

Data Directory

When you run polaris setup, the agent creates a data directory that holds everything it knows. The default structure looks like this: 

data/
├── .env              # API keys and provider config
├── docker-compose.yml
├── SOUL.md           # Agent personality & behavior rules
├── USER.md           # What the agent knows about you
├── wiki/             # Growing knowledge base
│   ├── index.md
│   └── ...
└── skills/           # Installed skills
    └── ...

Everything is plain text. You can read, edit, version-control, and back up every file.

Wiki & Memory

The wiki/ folder is Polaris's long-term memory. Every insight, note, and connection the agent makes ends up there as plain Markdown files. The wiki grows organically — the more you chat, the richer it becomes.

Key points:

  • Files are human-readable Markdown — no proprietary database
  • The agent reads its wiki before responding to ground itself in context
  • When it learns something worth remembering, it writes it back automatically
  • You can edit or delete any file by hand — the agent picks up changes on the next turn

SOUL.md defines the agent's personality and behavior. USER.md stores what it learns about you specifically. Both are just Markdown — edit them freely.

Tool Loop

Each conversation turn follows a tool loop:

  1. Reason — the agent thinks about your message
  2. Plan — it decides which tools to call (search the web, run a script, update the wiki, etc.)
  3. Act — it executes the tool calls
  4. Respond — it synthesizes the results into a reply
  5. Remember — if something is worth keeping, it writes it to the wiki

The loop is transparent — you can see what tools the agent calls and what it writes. No hidden behavior.

Skills

Skills extend the agent's capabilities. A skill is a self-contained package that adds targeted functionality without bloating the core agent.

Skills can:

  • Define new tools the agent can use
  • Include Python scripts running in isolated environments
  • Add domain-specific knowledge and behavior

The agent can write new skills for itself and download existing ones from the community. Skills live in the skills/ directory.

Interfaces

Ways to interact

Polaris exposes three interfaces: CLI, HTTP, and Telegram. All three share the same agent and the same memory.

CLI

The command-line interface is the primary way to interact with Polaris during development and debugging: 

# Start an interactive chat
polaris chat

# Send a single message
polaris chat "What do you know about my project?"

# Check agent status
polaris status

The CLI streams responses in real-time and shows tool calls as they happen.

HTTP API

The agent exposes a local HTTP server for programmatic access: 

# Send a message
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Polaris"}'

The API returns the full response including any tool calls made. Useful for building custom integrations or connecting other tools.

Telegram

Connect Polaris to Telegram for always-available access from your phone:

  1. Create a new bot via @BotFather on Telegram
  2. Add the bot token to your .env file during polaris setup
  3. Restart the agent — it will start listening for messages automatically

Messages are processed through the same tool loop as CLI and HTTP — the agent's memory and behavior are consistent across all interfaces.

Advanced

Going deeper

Configuration details for custom deployments and provider setup.

LLM Providers

Polaris works with any OpenAI-compatible API. Set the provider endpoint and model in your .env: 

# OpenAI
POLARIS_LLM_ENDPOINT=https://api.openai.com/v1
POLARIS_LLM_MODEL=gpt-4o
POLARIS_LLM_API_KEY=sk-...

# Ollama (local)
POLARIS_LLM_ENDPOINT=http://localhost:11434/v1
POLARIS_LLM_MODEL=llama3
POLARIS_LLM_API_KEY=ollama

# Any OpenAI-compatible provider
POLARIS_LLM_ENDPOINT=https://your-provider.com/v1
POLARIS_LLM_MODEL=your-model
POLARIS_LLM_API_KEY=your-key

Swap providers anytime — the agent's wiki and memory are model-independent.

Docker Setup

The docker-compose.yml generated by polaris setup handles the container lifecycle. The key configuration:

  • Image — the official Polaris Agent container
  • Volume — your data directory mounted at /data
  • Ports — 8080:8080 for the HTTP API
  • Env file — loads .env for API keys and provider config
# View logs
docker compose logs -f

# Restart after config change
docker compose restart

# Update to latest image
docker compose pull && docker compose up -d

Backup & Restore

Since everything is in one directory, backing up is straightforward: 

# Create a backup
tar -czf polaris-backup-$(date +%Y%m%d).tar.gz data/

# Restore from backup
tar -xzf polaris-backup-20240510.tar.gz

You can also use Git to version-control your wiki and configuration for incremental backups: 

cd data
git init
git add -A
git commit -m "checkpoint"

No proprietary database, no export tools, no lock-in. Your data is just files.

Still have questions? Open an issue on GitHub or check the README.