goloom

Lightweight, self-hosted social media planning for teams and AI agents.

Plan posts across Mastodon, Bluesky and Friendica from a single Go binary — no enterprise stack, no per-seat pricing.

goloom is a self-hosted social media planning application built as one Go binary (API + web UI). It helps teams plan posts across multiple social accounts without the heavy infrastructure and pricing model of typical enterprise-first tools.

Most tools in this space are powerful but heavy: complex stacks, many paid tiers, and product scope optimized for large organizations.

goloom was created for one focused outcome:

• plan posts across different social media accounts
• collaborate across teams
• keep operations simple
• integrate cleanly with AI agents such as OpenClaw

Composer — write once, preview per platform	Analytics — engagement & follower trends

• Single binary deployment: UI and API in one process.
• SQLite by default: no external database needed.
• PostgreSQL optional for larger deployments.
• Team workspaces with member roles (owner, editor, viewer).
• Scheduling, validation, per-account post versions, media library.
• Built-in analytics for post and account metrics.
• API-first architecture with bearer-token auth.
• OIDC support for browser sign-in.
• Mastodon onboarding can auto-register app credentials from instance URL.

Three ways to run goloom — pick one (full guide: Installation):

• Docker — docker run ... ghcr.io/goloom-app/goloom:latest (see Docker).
• Prebuilt binary — download a static Linux binary from the latest release (goloom_<version>_linux_amd64 / arm64), chmod +x, set ENCRYPTION_KEY + BOOTSTRAP_ADMIN_TOKEN and run it. The web UI is embedded; data goes to ./data/goloom.db (SQLite) by default.
• From source — build it yourself (below).

cp .env.example .env

Set required values:

ENCRYPTION_KEY=replace-with-a-long-random-secret
BOOTSTRAP_ADMIN_TOKEN=replace-with-a-strong-bootstrap-token

make build
./bin/goloom

Open http://localhost:8080.

Use the bootstrap token in the UI Settings screen. After first login, create normal API tokens and rotate bootstrap secrets.

goloom API is designed for both developers and AI agents. Professional documentation stack uses OpenAPI + Redocly.

• Primary: /v1/...
• Alias: /api/v1/... (same handlers, for tools expecting /api/v1)

Use bearer tokens:

Authorization: Bearer <oidc-id-token-or-api-token>

Health and auth status:

curl -s http://localhost:8080/healthz
curl -s http://localhost:8080/v1/auth/status

List providers:

curl -s http://localhost:8080/v1/providers

Get current identity:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/v1/me

• Discovery: /healthz, /v1/providers, /v1/auth/status
• Identity: /v1/me, /v1/me/api-tokens
• Teams: /v1/teams, /v1/teams/{teamID}/members
• Accounts: /v1/teams/{teamID}/accounts, OAuth start endpoints
• Posts: /v1/teams/{teamID}/posts, validation, versions, cancel
• Analytics: /v1/teams/{teamID}/analytics*, post analytics
• Admin: /v1/admin/*, provider instance management

For complete route list, see api/http.go.

The interactive API reference is rendered with Scalar and served by the website at /api/. It reads the OpenAPI spec directly, so there is no separate static build step.

Lint the OpenAPI spec:

make docs-api-lint

• source spec: docs/api/openapi.yaml (single source of truth)
• the spec is copied to website/public/openapi.yaml by make website-build

• Built-in MCP server (Streamable HTTP transport) at /mcp (enabled by default, MCP_ENABLED), authenticated with API tokens carrying read / write:draft / write:schedule / write / delete scopes (unscoped tokens have full access).
• Stable JSON responses across core endpoints.
• Predictable resource paths with team-scoped objects.
• Validation endpoint before scheduling: POST /v1/teams/{teamID}/posts/validate.
• API token lifecycle endpoints for secure agent onboarding.

The project website (Astro + Starlight) lives in website/: a marketing landing page, the documentation (3-column Starlight layout) and the Scalar API reference at /api/.

Local dev server:

make website-dev

Build static site (includes API docs):

make website-build

Generated output: website/dist/

Deployed via GitHub Pages on push to main when website/ or docs/api/ changes: the pages.yml workflow builds the site with make website-build and force-pushes website/dist to the org Pages repo goloom-app.github.io, which GitHub serves at the root URL https://goloom-app.github.io/.

• OAuth account connection
• optional automatic app registration via instance URL
• publishing and metrics (likes, reposts, replies)

• manual provider app credentials
• publishing and Mastodon-compatible metrics

• account connection with app password
• publishing and metrics support

Best for low-ops environments and small-to-medium teams.

DATABASE_URL=file:./data/goloom.db

Use when you need external DB operations and scale patterns:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/goloom?sslmode=disable

Upgrading PostgreSQL to a new major version (e.g. 16 → 18) is a dump & restore, not an in-place swap — see the PostgreSQL major upgrade guide.

A Helm chart is provided at deploy/helm/goloom (SQLite on a PersistentVolume, or external PostgreSQL; optional Ingress):

helm install goloom ./deploy/helm/goloom \
  --namespace goloom --create-namespace \
  --set secret.encryptionKey="$(openssl rand -hex 32)" \
  --set secret.bootstrapAdminToken="change-me-please" \
  --set config.publicBaseUrl="https://goloom.example.com"

See the Kubernetes (Helm) guide.

If you run Goloom with Docker PostgreSQL and want to move to the homelab CNPG deployment, see docs/migrations/docker-to-kubernetes-homelab.md.

Use the published multi-arch image (linux/amd64 + arm64) from GHCR:

docker run --rm \
  -p 8080:8080 \
  -e ENCRYPTION_KEY=replace-with-a-long-random-secret \
  -e BOOTSTRAP_ADMIN_TOKEN=replace-with-a-strong-bootstrap-token \
  -v "$(pwd)/data:/app/data" \
  ghcr.io/goloom-app/goloom:latest

For production, pin a version tag (e.g. ghcr.io/goloom-app/goloom:v0.1.0) instead of :latest. To build the image yourself: docker build -t goloom ..

nix develop
make run

Frontend-only dev server:

make frontend-dev

Recommended API-doc workflow in CI:

• run make docs-api-lint on pull requests to validate the OpenAPI spec
• the reference is published as part of the website (make website-build)

Start from .env.example. Common keys:

• APP_ENV, HTTP_ADDR, PUBLIC_BASE_URL
• DATABASE_URL
• ENCRYPTION_KEY
• BOOTSTRAP_ADMIN_*
• SCHEDULER_*
• OIDC_*
• MASTODON_*

goloom is intentionally optimized for:

• lower runtime overhead
• easier self-hosting
• practical team collaboration
• API-first automation for agent workflows

If you need broad enterprise suites, many commercial upsell modules, or advanced campaign ecosystems, other products may fit better. If you need a focused scheduler with strong API ergonomics and simple ops, goloom is the target shape.

• Provider access tokens are encrypted at rest.
• API tokens are stored as hashes.
• Set strong ENCRYPTION_KEY and rotate bootstrap/admin secrets after setup.

goloom follows Semantic Versioning and is intentionally pre-1.0 (0.x) — usable and self-hostable today, but breaking changes can still land between minor versions, so pin a version and read the notes before upgrading.

• Branching: development happens on feature branches; after testing they are merged into main (CI runs the full test suite on every PR).
• Nightly: every push to main publishes ghcr.io/goloom-app/goloom:nightly, always built from the latest main state (plus a per-commit nightly-<sha> tag). Use it to try upcoming features; it is not a release.
• Releases are automated from Conventional Commits via release-please: a release PR maintains CHANGELOG.md and the version; merging it tags vX.Y.Z, publishes a GitHub Release with prebuilt Linux binaries (amd64/arm64), and pushes the versioned ghcr.io/goloom-app/goloom image — :latest moves only on releases.
• The running version is reported by GET /healthz and the agent discovery doc.
• The REST API has its own contract version under /v1, independent of the app version; it changes only on breaking API changes.

goloom grew out of my own needs as a self-hosted tool. It is built with heavy use of AI, and I use it as a testbed for exploring methods for efficient, AI-assisted development.

Licensed under the MIT License.