sphericon

README

Sphericon

Open-core marketing automation you can run yourself.
Documentation · Releases · Self-hosting

About

Sphericon helps a business know its audience and talk to it at the right moment: it collects who your contacts are and what they do on your site or in your product, groups them into segments, and sends them email. Everything lives in your own workspace on your own infrastructure, so the customer data stays yours. It is a self-hostable alternative to tools like Drip, without the lock-in.

Features

• Contacts and events — one profile per person, built from imports, the API and the tracking snippet on your site.
• Segments and tags — audiences defined by rules over contacts, tags and events.
• Broadcasts — one-off email to a segment, with per-broadcast stats.
• Automations — sequences triggered by what a contact does, with waits and emails.
• Transactional email — send single messages through the API.
• Deliverability built in — unsubscribes, bounces and spam complaints are honored automatically, mail is signed with your own DKIM key and sent with one-click unsubscribe, so you never write to someone who asked you to stop.
• API and webhooks — a workspace-scoped API with scoped tokens, and webhooks for what happens next.
• Agent-ready — an MCP server lets an AI agent draft campaigns; sending stays opt-in per token.
• Privacy tools — GDPR export and erasure.
• Multi-user workspaces — owners, admins and members, with two-factor sign-in.

Getting started

One program and one database: a Go binary (or Docker image) with the web app, the tracker and the migrations built in, plus PostgreSQL. No Redis, no object storage, no separate worker.

With Docker Compose, which runs PostgreSQL, the migrations and the app together:

# 1. Download the Compose file and the example environment
curl -fsSLO https://raw.githubusercontent.com/getsphericon/sphericon/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/getsphericon/sphericon/main/compose.env.example -o .env

# 2. Fill in .env: POSTGRES_PASSWORD, SPHERICON_JWT_SECRET (openssl rand -hex 32) and
#    SPHERICON_ENCRYPTION_KEY (docker run --rm ghcr.io/getsphericon/sphericon:latest genkey)

# 3. Start it
docker compose up -d

Then put a reverse proxy with HTTPS in front of port 3000 and open it to create your account. The full guide covers HTTPS, the first run, plain Docker, the single binary and Kubernetes (Helm): self-hosting. Every environment variable is in configuration.

Images are published to ghcr.io/getsphericon/sphericon (linux amd64/arm64) on every release, and release archives for linux and darwin are attached to each GitHub Release.

Tech stack

Go (ogen, ent, river, watermill) and PostgreSQL on the backend; React, Vite and Mantine on the frontend; TypeSpec as the single source of truth for the API contracts.

Contributing

Setup with a single prerequisite (mise), the code generation pipeline, dev accounts and the pull request rules are in CONTRIBUTING.md. Architecture and conventions are in AGENTS.md, the domain language in GLOSSARY.md.

License

Sphericon is open-core. The core is licensed under the GNU AGPL-3.0 (LICENSE); the Enterprise features under ee/ are commercial and source-available (ee/LICENSE). See LICENSING.md for the boundary. Contributions need a signed CLA.

Security

To report a vulnerability, see SECURITY.md.

Documentation

Overview

Package sphericon is the module-root package. It exists only to embed the goose migration files (which live in ./migrations at the repo root) so the single binary can apply them itself (goose), with no migration tool on the host. The embed directive must live at or above the migrations directory in the source tree — go:embed cannot reference parent paths — hence this file sits at the module root.

Package sphericon holds repository-root assets that Go code embeds.

Index

• Variables

Variables

var ExternalOpenAPI []byte

ExternalOpenAPI is the generated external (/api) OpenAPI document. The MCP surface (internal/mcpserver) projects its tools from it, so the tool list can never drift from the contract (ADR 0016).

var MigrationsFS embed.FS

MigrationsFS holds the committed migration files (goose format, diffed from the ent schema). Consumed by cmd/server. Written by `mise run db:generate`, never by hand.

var TelemetryOpenAPI []byte

TelemetryOpenAPI is the generated Telemetry report OpenAPI document (ADR 0032), the published contract every built report is validated against (internal/telemetryschema).