README
¶
GoRun
A self-hosted CMS for your team and AI agents.
العربية · Documentation · Releases · Use an assistant · Contribute
Try it locally
On macOS or Linux, copy and paste this whole block. No Go, Docker, database setup or administrator privileges required.
(
set -eu
installer="$(mktemp)"
trap 'rm -f "$installer"' EXIT
curl -fsSL https://raw.githubusercontent.com/zadstack/gorun/main/install.sh -o "$installer"
sh "$installer"
) &&
export PATH="$HOME/.local/bin:$PATH" &&
gorun start --data "$HOME/.local/share/gorun/site"
The installer detects Intel or ARM, downloads the latest release, verifies its SHA-256 checksum, and installs GoRun for your user. The block configures this terminal automatically, and the installer adds the default executable directory to your shell startup file for future terminals. No manual PATH setup. Your browser opens, SQLite and the default theme are prepared, and your first admin password appears once in the terminal. Save it. On first sign-in, choose your own password, email, site name and language. Restarting preserves your site and accounts.
The quick start requires GoRun 0.4.0 or newer. The installer refuses older releases without changing an existing installation.
The executable lives at ~/.local/bin/gorun; your local site lives at ~/.local/share/gorun/site. Stop the server with Ctrl+C. Repeating the block uses the same site. LAN access is a public, read-only preview; administration stays on localhost. Use --local-only when starting manually to disable LAN access. Local setup and recovery.
For a public deployment, follow the production guide or Docker / Coolify guide. The local preview is intended for development.
Start with your AI assistant
Prefer help from an assistant? Copy this into any assistant that can use a terminal on your computer:
Set up GoRun locally from https://github.com/zadstack/gorun.
Read the official README and installation guide first.
Check my operating system, architecture, and any existing GoRun site.
Use the official release installer with its checksum verification.
Preserve existing data, users, themes, settings, and credentials.
Start the site and verify the public page and admin sign-in page respond.
Keep generated passwords and keys in the local terminal, out of chat and logs.
Let me sign in and complete first-login setup in the browser.
Report the local URL, data directory, and how to stop and restart the server.
If you cannot run a local terminal, provide the official commands for me to run.
The instructions are tool-neutral. A chat-only assistant can explain the steps but cannot install software on your computer. Assistant setup guide.
Cloudflare Edge — in development
GoRun Edge is being developed as a separate Workers-based edition. The current milestone provides site-scoped manager permission contracts. The Worker runtime, storage/admin integration and a tested deployment template remain on the Edge roadmap. A Deploy to Cloudflare button will be added after the template passes a real deployment test.
Why GoRun?
- Your content and infrastructure. A Go executable and SQLite, hosted by you. No Node.js or PHP at runtime.
- Arabic and English from the start. A bilingual dashboard with native RTL support and responsive site themes.
- A complete editorial workflow. Structured content, drafts, reviews, scheduled publishing, revision history and explicit staff permissions.
- Agents with boundaries. MCP tools, scoped agent keys, human approvals for sensitive changes and an audit trail. Separate REST keys serve other integrations.
Write, review and publish
Manage posts, pages, custom content types, fields, media and navigation in one place. Give editors, authors and contributors the permissions they need, and review changes before publishing.
Editorial workflow · WordPress migration
Build a site you can make your own
Start with a bundled theme, create pages with section-based layouts, and preview before publishing. Child themes and filesystem templates let developers customize the result. Activating a theme does not create starter pages; use the site builder for starter content.
Site builder · Theme development · Theme reference
Work with agents, keep the decisions
Connect an MCP client with an AI agent key. Its scopes are bounded by its owner's permissions; publishing, deleting and changing sensitive settings require human approval by default. REST integration keys are separate from agent keys.
Canvases bring selected content, instructions and agent results into one workspace. Results become private notes for review and do not publish content automatically. Configure your provider or agent connection before running it.
MCP and permissions · Canvases · REST API
Operate with confidence
Schedule daily or weekly local backups, track verified success and storage, and inspect failure alerts. Preview a disposable, read-only restore on localhost before restoring into a new directory. gorun doctor diagnoses an existing site without migrating or repairing it.
Backups and recovery · Local diagnostics
Find your next step
| I want to… | Start here |
|---|---|
| Install or deploy GoRun | Installation · Production |
| Create or customize a theme | Theme tutorial |
| Build an integration | Plugin tutorial · REST · MCP |
| Build on the Go core | Architecture |
| Operate an existing site | Backups · Upgrades · Troubleshooting |
| Explore everything | Documentation index |
Project status
GoRun is under active development. The current release is 0.4.0; the main branch may contain features awaiting release.
Run one server process per SQLite data directory. Canvases are private to their owner with explicit agent access. Full-site generation from a single prompt and an automatic core updater are not available. Backups restore into a new directory; switching live traffic remains an operator action. Provider-backed generation and payments require valid credentials and deployment-specific checks.
Screenshots show an isolated local installation with fictional demonstration content. They do not show customer data or a connected provider.
Contribute
Bug reports, documentation improvements and contributions are welcome. Read the contribution guide and security policy. GoRun is released under GNU AGPL v3; see NOTICE and the changelog.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gorun
command
Command gorun runs the GoRun CMS.
|
Command gorun runs the GoRun CMS. |
|
examples
|
|
|
extensions/hello-http
Package hello is a minimal GoRun extension speaking the HTTP bridge protocol (docs/EXTENSIONS.md).
|
Package hello is a minimal GoRun extension speaking the HTTP bridge protocol (docs/EXTENSIONS.md). |
|
extensions/hello-http/cmd/hello-http
command
Command hello-http runs the hello example extension:
|
Command hello-http runs the hello example extension: |
|
internal
|
|
|
admin
Package admin serves the core admin screens: dashboard widgets, users, roles, general and mail settings, system health and jobs, API keys, the audit viewer and the global admin search.
|
Package admin serves the core admin screens: dashboard widgets, users, roles, general and mail settings, system health and jobs, API keys, the audit viewer and the global admin search. |
|
api
Package api is the REST layer: it mounts every operation registered in kernel.APIRegistry under /api/v1 (with scope enforcement, panic recovery and a JSON default content type), serves the generated OpenAPI 3.1 document at /api/v1/openapi.json and the Scalar reference at /api/docs, and provides the core operations (/site, /me, /health) plus helpers (pagination, decoding, error envelopes) for other modules' handlers.
|
Package api is the REST layer: it mounts every operation registered in kernel.APIRegistry under /api/v1 (with scope enforcement, panic recovery and a JSON default content type), serves the generated OpenAPI 3.1 document at /api/v1/openapi.json and the Scalar reference at /api/docs, and provides the core operations (/site, /me, /health) plus helpers (pagination, decoding, error envelopes) for other modules' handlers. |
|
api/apitest
Package apitest boots GoRun for API tests and drives /api/v1 with a bearer API key.
|
Package apitest boots GoRun for API tests and drives /api/v1 with a bearer API key. |
|
audit
Package audit writes and reads the audit log.
|
Package audit writes and reads the audit log. |
|
auth
Package auth provides users, roles and permissions, sessions, CSRF, API keys, magic links, login rate limiting and the admin shell (login, setup, locale switch).
|
Package auth provides users, roles and permissions, sessions, CSRF, API keys, magic links, login rate limiting and the admin shell (login, setup, locale switch). |
|
backup
Package backup makes and lists data-directory backups: a consistent copy of the database (VACUUM INTO) and a tar.gz of data trees and local recovery configuration, both under <data>/backups/<UTC timestamp>.
|
Package backup makes and lists data-directory backups: a consistent copy of the database (VACUUM INTO) and a tar.gz of data trees and local recovery configuration, both under <data>/backups/<UTC timestamp>. |
|
commerce
Package commerce sells access to MCP servers: products → Stripe Checkout → orders → customers → entitlements → provisioning on billing servers over the signed mcp-billing/v1 protocol (spec §4.6, docs/COMMERCE.md).
|
Package commerce sells access to MCP servers: products → Stripe Checkout → orders → customers → entitlements → provisioning on billing servers over the signed mcp-billing/v1 protocol (spec §4.6, docs/COMMERCE.md). |
|
commerce/fakebilling
Package fakebilling is an in-memory billing server implementing the mcp-billing/v1 protocol (see docs/COMMERCE.md) for tests and local e2e runs: signature verification (same scheme as the real servers), Idempotency-Key replay on mutations, and failure injection.
|
Package fakebilling is an in-memory billing server implementing the mcp-billing/v1 protocol (see docs/COMMERCE.md) for tests and local e2e runs: signature verification (same scheme as the real servers), Idempotency-Key replay on mutations, and failure injection. |
|
config
Package config loads GoRun configuration.
|
Package config loads GoRun configuration. |
|
content
Package content manages content types, custom fields, content items, revisions and queries.
|
Package content manages content types, custom fields, content items, revisions and queries. |
|
db
Package db opens the GoRun SQLite database and provides migration, transaction, ID and time helpers shared by every module.
|
Package db opens the GoRun SQLite database and provides migration, transaction, ID and time helpers shared by every module. |
|
diagnostics
Package diagnostics stores bounded classifications, never raw log messages or attributes.
|
Package diagnostics stores bounded classifications, never raw log messages or attributes. |
|
ext
Package ext is the extension system (spec §4.9): extensions are external programs described by a manifest.
|
Package ext is the extension system (spec §4.9): extensions are external programs described by a manifest. |
|
hooks
Package hooks provides WordPress-style actions, filters and events.
|
Package hooks provides WordPress-style actions, filters and events. |
|
httpx
Package httpx holds shared HTTP plumbing: middleware, the API response envelope, form binding/validation, the SSRF-safe client and the admin template renderer.
|
Package httpx holds shared HTTP plumbing: middleware, the API response envelope, form binding/validation, the SSRF-safe client and the admin template renderer. |
|
i18n
Package i18n loads translation catalogs and resolves the request locale.
|
Package i18n loads translation catalogs and resolves the request locale. |
|
jobs
Package jobs is the DB-backed job queue: enqueue, workers with retry and exponential backoff, and a coarse cron scheduler.
|
Package jobs is the DB-backed job queue: enqueue, workers with retry and exponential backoff, and a coarse cron scheduler. |
|
kernel
Package kernel defines the Module contract and boots GoRun: it opens the database, runs each module's migrations, lets modules register into shared registries, and assembles the HTTP handler.
|
Package kernel defines the Module contract and boots GoRun: it opens the database, runs each module's migrations, lets modules register into shared registries, and assembles the HTTP handler. |
|
launch
Package launch serves the public /start journey (customer onboarding chrome) and relies on launch overlay assets embedded under web/launch.
|
Package launch serves the public /start journey (customer onboarding chrome) and relies on launch overlay assets embedded under web/launch. |
|
mailer
Package mailer sends transactional email over SMTP or Resend using mail.* settings.
|
Package mailer sends transactional email over SMTP or Resend using mail.* settings. |
|
mcp
Package mcp is GoRun's official Model Context Protocol server: the streamable HTTP endpoint at /mcp (bearer API keys only) and the stdio transport behind `gorun mcp --key`.
|
Package mcp is GoRun's official Model Context Protocol server: the streamable HTTP endpoint at /mcp (bearer API keys only) and the stdio transport behind `gorun mcp --key`. |
|
media
Package media manages the media library, storage drivers and image variants.
|
Package media manages the media library, storage drivers and image variants. |
|
membership
Package membership provides explicit local grants, never payment assertions.
|
Package membership provides explicit local grants, never payment assertions. |
|
menus
Package menus manages navigation menus and their items.
|
Package menus manages navigation menus and their items. |
|
metrics
Package metrics serves an optional Prometheus text exposition at GET /metrics.
|
Package metrics serves an optional Prometheus text exposition at GET /metrics. |
|
redirects
Package redirects manages URL redirects.
|
Package redirects manages URL redirects. |
|
saas
Package saas preserves app ownership, subscriptions and atomic usage independently of commerce provisioning.
|
Package saas preserves app ownership, subscriptions and atomic usage independently of commerce provisioning. |
|
seo
Package seo renders SEO meta tags, sitemap.xml and robots.txt.
|
Package seo renders SEO meta tags, sitemap.xml and robots.txt. |
|
settings
Package settings is the key/value settings store.
|
Package settings is the key/value settings store. |
|
settings/settingsmod
Package settingsmod is the settings kernel.Module.
|
Package settingsmod is the settings kernel.Module. |
|
site
Package site is the public front controller: it maps public URLs to content, terms and listings and renders them through the active theme (theme.Service).
|
Package site is the public front controller: it maps public URLs to content, terms and listings and renders them through the active theme (theme.Service). |
|
starter
Package starter holds the content a new site starts with (Arabic sample posts, pages and categories as WXR), so a fresh site is never empty.
|
Package starter holds the content a new site starts with (Arabic sample posts, pages and categories as WXR), so a fresh site is never empty. |
|
taxonomy
Package taxonomy manages taxonomies, terms and their assignment to content.
|
Package taxonomy manages taxonomies, terms and their assignment to content. |
|
theme
Package theme loads themes, resolves the template hierarchy and renders the public site.
|
Package theme loads themes, resolves the template hierarchy and renders the public site. |
|
theme/fake
Package fake holds in-memory implementations of the services the theme engine and the site front controller consume (content, taxonomy, media, menus, redirects, seo), for tests.
|
Package fake holds in-memory implementations of the services the theme engine and the site front controller consume (content, taxonomy, media, menus, redirects, seo), for tests. |
|
webhooks
Package webhooks sends signed HTTP notifications of site events (content, media, menus, forms, sign-ins, orders, migrations) to subscribed endpoints, with retries, a delivery log, redelivery and secret rotation.
|
Package webhooks sends signed HTTP notifications of site events (content, media, menus, forms, sign-ins, orders, migrations) to subscribed endpoints, with retries, a delivery log, redelivery and secret rotation. |
|
workagents
Package workagents runs owner-scoped text agents through GoRun's job queue.
|
Package workagents runs owner-scoped text agents through GoRun's job queue. |
|
wpmigrate
Package wpmigrate is the WordPress Migrator (spec §4.7): an honest Discovery Report, a 7-step wizard, a job-based import pipeline with resume/retry/dry-run, Gutenberg conversion, media download and URL rewrite, Yoast mapping, a WooCommerce catalog adapter and a WXR fallback.
|
Package wpmigrate is the WordPress Migrator (spec §4.7): an honest Discovery Report, a 7-step wizard, a job-based import pipeline with resume/retry/dry-run, Gutenberg conversion, media download and URL rewrite, Yoast mapping, a WooCommerce catalog adapter and a WXR fallback. |
|
wpmigrate/gutenberg
Package gutenberg parses WordPress block markup (<!-- wp:ns/name {json} --> … <!-- /wp:ns/name -->) into a tree and converts it to clean HTML for GoRun (spec §4.7).
|
Package gutenberg parses WordPress block markup (<!-- wp:ns/name {json} --> … <!-- /wp:ns/name -->) into a tree and converts it to clean HTML for GoRun (spec §4.7). |
|
wpmigrate/wxr
Package wxr parses WordPress eXtended RSS exports (Tools → Export), the fallback source when the REST API hides data (postmeta such as the MCBB product mapping, drafts, menus).
|
Package wxr parses WordPress eXtended RSS exports (Tools → Export), the fallback source when the REST API hides data (postmeta such as the MCBB product mapping, drafts, menus). |
|
pkg
|
|
|
cli
Package cli is the GoRun command line.
|
Package cli is the GoRun command line. |
|
edge
Package edge defines portable GoRun Edge site and manager authorization contracts.
|
Package edge defines portable GoRun Edge site and manager authorization contracts. |
|
themekit
Package themekit is the shared catalog theme contract: validation helpers for ship-with and custom themes.
|
Package themekit is the shared catalog theme contract: validation helpers for ship-with and custom themes. |
|
Package themes bundles the default theme for standalone local starts.
|
Package themes bundles the default theme for standalone local starts. |
|
tools
|
|
|
loadtest
command
Command loadtest runs a practical HTTP load harness against a local GoRun SQLite instance (or an existing base URL).
|
Command loadtest runs a practical HTTP load harness against a local GoRun SQLite instance (or an existing base URL). |
|
wp-record
command
Command wp-record records a WordPress site's public REST responses into a directory for local migration rehearsals (spec §7 "recorded fixture server").
|
Command wp-record records a WordPress site's public REST responses into a directory for local migration rehearsals (spec §7 "recorded fixture server"). |
|
Package web embeds the admin templates and static assets.
|
Package web embeds the admin templates and static assets. |