Build your website with an AI app
webspine works with any AI app that can edit project files. It works best with Claude Code in the Claude desktop app, connected to your server as shown below.
Works best with Claude Code on your server
Connect the Claude desktop app to your server over SSH. Claude then builds the website where it will run, so publishing is not a separate step.
In Claude, open Code. Open the environment selector under the prompt box and choose New environment. On the SSH tab, open Host, select Add SSH connection… and enter the login for your server.
Environment selector › New environment › SSH › Host
Add SSH connection
- Name
- My web server
- SSH host
- deploy@my-domain.com
- SSH port
- 22
- SSH key (optional)
- ~/.ssh/id_ed25519
Still on the SSH tab, choose the new connection and the folder on the server where the website should live, then select Create environment. The first time it connects, Claude installs Claude Code on the server for you.
Environment selector › New environment
New environment
- Host
- My web server
- Folder
- ~/my-website
Claude now works directly on your server. Describe your website, then open your domain in the browser to look at the result.
New session
Build me a website with webspine.org in this folder. Read https://www.webspine.org/docs#technical-reference first. It is for [my idea or business]. I need [my pages]. Make it feel [my preferred style]. The domain [my-domain.com] points to this server. Set it up so the web server serves the public/ folder, and tell me when I can look at it.
Your website, on your server
Open it in your browser and ask for changes.
Later changes work the same way. Claude edits the files on the server, so there is nothing to upload or deploy afterwards.
New session
Add a page for my latest projects. Back up the site first, then tell me what you changed.
You need the Claude desktop app and a server or hosting package with SSH access, PHP 8.3 or newer and SQLite. Without SSH access, choose Local instead and ask Claude to help you publish the finished site.
Claude Code documentation on SSH sessionsWith another AI app
ChatGPT Desktop, OpenCode and similar apps work too. They usually build the site in a folder on your computer, so publishing it is a separate step at the end.
Tell your AI what to build
A portfolio, a studio website, a place for your next project. Describe its purpose, the pages you need, and the style you have in mind. Use this prompt to start.
Build me a website using webspine.org. My website is for: [your idea or business] It needs these pages: [your pages] The look and feel should be: [your style] Create the site and show me a preview so we can refine it together.
Review the preview together
Your AI builds the first version. Look at the preview and tell it what to change: “Make the headline clearer.” “Add my latest work.” “Use warmer colors.” Keep going until the website feels like yours.
Check the details and publish
Review the pages, try the navigation, and check the website on desktop and mobile. Ask your AI to refine the details until the design and content feel right. Your finished website is yours to keep and develop.
Later changes work the same way
New pages, fresh copy, a different design. Come back to your AI, explain your next idea, and let it work on the same website.
How webspine works
For your AI tool and anyone building or maintaining webspine by hand. Follow the installation guide, understand the project structure, and use the reference below to develop and deploy the site.
Read the versioned framework reference on GitHubQuick start
For a new website, get a full bootstrap ZIP from an official stable GitHub release and extract it. A core-only ZIP updates an existing installation; it cannot create a site. You need PHP 8.3+ with pdo_sqlite, openssl for SMTP, and zip for packaging and updates. No Composer, npm, or build step.
php core/bin/console.php install
php core/bin/console.php health
php -S localhost:8080 -t public public/router.phpVisit localhost:8080. Installation explicitly creates SQLite tables, records schema version 1, and selects the Starter theme. Re-running it preserves settings and pages. Requests never install or migrate a database.
public/ as its only document root.Principles
The core goal of webspine is to let you build, extend, and maintain your own website entirely with AI. Familiar code, a readable structure, and explicit contracts give an AI contributor a project it can understand.
Bring your own AI app with access to the project files, such as ChatGPT Desktop, Claude Code, or OpenCode. The project stays independent of any AI vendor; you can also edit every file by hand.
- Keep the core small and understandable.
- Keep content and routes in
site/, presentation insite/themes/, and capabilities insite/plugins/. - Choose providers explicitly. Avoid hidden configuration in the database.
- Preserve a theme’s identity. Every website can look different.
AI contributors should inspect existing work, make scoped changes, run relevant checks, report gaps, and protect secrets.
Project structure
core/Framework, bundled providers, tools, tests, and guidessite/Site identity, page definitions, routes, and installationsite/content/Editable PHP content arrays; this website adds English/German catalogs through site-owned localizationsite/themes/Templates, shared layouts, scoped CSS, and browser JSsite/plugins/Provider and feature extensions with manifestsconfig/Private provider selection and credentialsstorage/SQLite, update stages, backups, and lockspublic/The only web document rootcore/bin/Installation, health checks, packaging, and updates.dist/Generated release ZIPs and checksumscore/tests/Dependency-free integration testscore/docs/Architecture, deployment, and contributor guidanceThe SQLite provider implements storage, settings, pages, and optional Entities CRUD. Plugins declare typed entities and use shared create/read/list/update/delete operations after running php core/bin/console.php entities:install. See core/docs/entities.md and site/plugins/catalog/ for examples. Feature plugins use interfaces, never provider-specific SQL. MariaDB and PostgreSQL adapters will need their own queries, migrations, and data-transfer tooling.
SQLite also supports the optional EntityQueries and EntityIndexes capabilities on the Entities service. Use EntityFilter and EntityQuery for typed filtering, sorting, search() and count(); check provider capabilities explicitly. Declare indexes with defineIndex() and run entities:install to create them. Queries, health checks and core updates never create indexes or rewrite records.
Read the entity query and index referenceConfiguration
Copy config/example.php to config/local.php. Keep the local file private. Select providers and enabled feature plugins here, before database access.
'providers' => ['storage' => 'sqlite', 'mail' => null],
'plugins' => [],
'sqlite' => ['path' => 'storage/site.sqlite'],Select 'mail' => 'smtp' and fill in the SMTP configuration to enable bundled PHPMailer. The provider requires TLS and sends plain-text messages. Mail and feature plugins are disabled by default in the Starter. The optional queued contact example is adopted explicitly; see the contact and queue sections below.
SQLite belongs on local disk with modest write concurrency. Keep the database and update backups outside the document root.
Themes
Duplicate site/themes/starter/, choose a lowercase directory ID, and update theme.json. Keep API version 1 and provide layout.php plus the templates referenced by site/pages.php. The shared layout wraps every page. Edit wording in site/content/, page titles in site/pages.php, and identity in site/meta.php; theme files own markup and styles.
php core/bin/console.php theme your-themeThe active theme is stored by the settings service. Assets are served only from the selected theme’s assets/ folder through a constrained route. Scope CSS under a theme class, escape strings with e(), and keep JavaScript progressively enhanced.
PHP themes and plugins execute trusted code. Review them before installing; they are not sandboxed.
Reusable PHP components live in site/themes/<id>/components/. Pass explicit props with $app->theme->component(); components receive $props and $ui, without page variables or services. Pages and layouts also receive $ui for nested component(), id(), and assetUrl() calls. Use e($ui->assetUrl('style.css')) for a theme asset URL with a content-hash version. Page and layout scopes are separate: pass shared values in render data and access reserved-name collisions through $data. See core/docs/site.md for examples and rendering-lifecycle rules, including refresh() after manual settings or file changes on a reused App.
Page paths and explicit redirects.
Declare an optional path in site/pages.php to register a GET/HEAD page route. slash accepts preserve (the default), strip or append; strip/append add a 308 redirect for the alternate slash form and retain the raw query string. Remove the equivalent manual GET route before adopting a path: duplicate exact or matching pattern routes fail. Existing site routes remain intact during core updates. Use Response::redirect() for validated local redirects; page paths do not generate SEO canonical tags or multilingual routes.
// site/pages.php
'about' => ['path' => '/about', 'slash' => 'strip',
'template' => 'page', 'title' => 'About'],Plugins and services
Custom plugins live in site/plugins/; bundled providers live in core/plugins/. IDs must be unique across both directories. Every plugin declares its ID, semantic version, API, and dependencies in plugin.json. The entry file returns an object implementing Webspine\Contracts\Plugin.
{
"id": "my-feature", "version": "0.1.0", "api": 1,
"dependencies": {"field-notes": "0.1.0"}
}public function register(App $app): void {
$pages = $app->services->get(Pages::class);
$app->router->get('/hello', function () use ($pages, $app) {
$page = $pages->find('hello');
return $app->theme->render('page', [
'title' => $page['title'], 'body' => $page['body'],
]);
});
}The registry accepts implementations of declared interfaces and rejects duplicate registrations. Providers register services; feature plugins consume them. Providers must be selected in private configuration rather than loaded implicitly as dependencies.
GET/POST handlers can receive Webspine\Request; pattern handlers receive ($matches, $request). Use query(), header(), form(), or json() and validate types. Bodies are limited to 64 KiB and queries to 8 KiB; form() supports URL-encoded bodies, not multipart uploads. POST routes do not add authentication, CSRF, validation, or abuse protection automatically. The copied contact example provides its own session, validation and abuse protection, and queues delivery through the bundled job-queue.
Visit the working example pluginDiscover plugin commands.
Enabled trusted plugins can register local operator commands through cli.register and ConsoleCommands. help lists their commands; help <command> shows usage. help --core avoids booting site configuration for diagnosis. Command handlers own argument validation and storage setup; discovery never installs or migrates storage. The legacy core/plugins/job-queue/cli.php commands remain supported.
php core/bin/console.php help
php core/bin/console.php help job-queue:work
php core/bin/console.php help --coreContact forms that save first.
Give visitors a way to reach you. The copyable contact example saves valid messages to the durable job queue before a background worker sends them through your configured Mail provider. A success notice means saved for delivery. The Starter does not enable a form automatically.
Copy plugin.php, plugin.json, FormText.php, ContactForm.php and MailDelivery.php from core/docs/examples/contact-form/ into site/plugins/contact-form/. Copy the example template, styles and content into your selected theme and site content, or adapt your existing presentation. Merge the settings below into private configuration, append the plugin to your existing list, configure SMTP and install queue storage. The bundled job-queue dependency loads automatically.
// Merge into private config/local.php; preserve other settings.
'plugins' => ['contact-form'],
'contact_form' => [
'recipient' => 'you@example.com',
'path' => '/contact-example',
'retry' => ['max_attempts' => 30],
],Since 0.1.12, a matching expired form token preserves safe input and provides a fresh token for review and resubmission. Missing or foreign tokens discard input. Exact successful replays in the same session redirect to success without adding another job. Field limits match native browser UTF-16 code units; new payload version 2 remains compatible with delivery of existing version 1 jobs.
New contact jobs default to 30 total delivery attempts. Configure retry.max_attempts as an integer 1–100. Exponential waits grow from one minute to one hour; with 30 attempts, the final attempt is scheduled about 24 hours 3 minutes after the first, excluding transport time and cron delays. Existing jobs retain their saved attempt limit. SMTP delivery is at least once, so crash-related duplicate delivery remains possible.
The current copyable example saves the validated email field as a Reply-To snapshot. Bundled SMTP supports MailWithReplyTo and keeps the fixed recipient and configured From identity. Set contact_form.reply_to_field to another email field, or null to disable it for new jobs. Providers without the capability fall back to ordinary Mail; the visitor email stays in the body. Older queued jobs without a Reply-To snapshot keep their original behavior. Reply-To does not authenticate the visitor or guarantee delivery.
Core updates preserve copied site plugins. To adopt newer contact features, review and copy the current example files, including FormText.php, with compatible content keys and the declared job-queue dependency. Preserve private settings, templates and existing queued data; no queue schema migration is required. This website uses its own adapted plugin at /feedback and /de/feedback; a core upgrade alone does not add the new example’s Reply-To behavior to that copy.
Read the contact-form adoption guideA reusable queue for background work.
The optional bundled job-queue plugin separates durable saving from background processing. Consumers register handlers for named, versioned job types. Payloads are extensible JSON objects, bounded to 64 KiB and limited depth. Dedupe keys reject conflicting data; leased claims and claim tokens protect concurrent workers. Generic jobs default to five attempts, independently of the contact form.
Install storage explicitly, then schedule work using an absolute script path and your PHP executable, for example every minute. Each invocation processes at most ten jobs. Missing or paused handlers consume no attempts. There is no web worker endpoint and no sending during a form request. Keep storage/job-queue private and writable by the trusted web/CLI group.
php core/bin/console.php job-queue:install
php core/bin/console.php job-queue:status
php core/bin/console.php job-queue:work
php core/bin/console.php job-queue:health
php core/bin/console.php job-queue:retry <job-id>
php core/bin/console.php job-queue:prune 30Since 0.1.13, status includes pending/due ages, expired leases and worker start/finish activity. The private health command returns JSON warnings and a nonzero exit status when work needs attention. job_queue.stale_after_seconds defaults to 900; allowed integers are 60–604800. Future scheduled retries are excluded from overdue warnings. Monitor the command externally; a heartbeat does not prove mail delivery. Public /health stays independent of the delivery backlog.
CLI work automatically removes up to 1,000 completed jobs per normal invocation once they are at least 30 days old, even when no delivery jobs are ready. job_queue.retention_days accepts 1–3650 or null to disable automatic cleanup. Pending, processing and failed jobs are never removed automatically. Review failed jobs before retrying or pruning; explicit prune 30 also removes terminal-failed jobs beyond its retention period. Cleanup removes payloads and dedupe history; manage backup retention separately. Keep the worker scheduled and use consistent SQLite backups for WAL databases.
'job_queue' => [
'stale_after_seconds' => 900,
'retention_days' => 30, // 1–3650; null disables automatic cleanup.
],Simple analytics, without visitor tracking.
spine-analytics is an optional plugin bundled under core/plugins/spine-analytics. It counts aggregate requests and page visits without browser scripts, cookies, visitor IDs or stored IP addresses. These are request counts, not unique visitors. Collection and browser reporting are disabled by default.
Append spine-analytics to your existing plugin list and merge the settings below. Allowlist fixed public paths only, enable collection deliberately and run its installer explicitly. It owns a separate SQLite database at storage/spine-analytics/counts.sqlite; normal installation and core updates do not initialize analytics storage. Never also install a site plugin with the same ID.
// Append spine-analytics to the existing plugins list.
'spine_analytics' => [
'enabled' => true,
'preview' => false,
'report_enabled' => false,
'pages' => ['/', '/docs'],
],php core/plugins/spine-analytics/cli.php install
php core/plugins/spine-analytics/cli.php report 30Aggregates retain 90 UTC calendar days and expire on the next counted request. Queries and fragments are discarded; unlisted paths are combined as [other]. Optional coarse device metrics use request headers without fingerprinting. Only requests reaching PHP count; assets, /health and /_insights are excluded. Protect exports and backups separately.
Keep preview=false in production. A browser report at /_insights requires report_enabled=true, HTTPS and a configured password hash; follow the bundled guide to set it up. CLI reports and offline HTML exports remain private. Collection failures do not replace website responses.
Read the analytics installation and privacy guideCore updates
Core releases carry an exact file inventory with SHA-256 hashes, version, PHP minimum, and API compatibility. Updates validate and stage the archive, check compatibility and health, then activate under an exclusive lock. Failed health checks roll back changed files. A persistent recovery journal blocks requests after an interrupted activation until recovery.
php core/bin/console.php package
php core/bin/console.php update /path/to/core-release.zip
php core/bin/console.php rollback
php core/bin/console.php recoverSite files, themes, custom plugins, config, and data are preserved. Bundled providers in core/plugins/ update with the framework. Create your website from a bootstrap once; use core release archives for framework updates. Pulling or copying the upstream repository over a customized site does not provide this preservation guarantee. Core updates do not migrate databases. Back up the site separately before upgrading. Drain production workers and reset OPcache after activation.
Deployment
Set your Apache or nginx document root to public/. Route requests to index.php; the included Apache configuration requires mod_rewrite and override permissions. Disable directory indexes and deny arbitrary PHP files. See core/docs/deployment.md for copyable Apache, nginx, and CloudPanel examples and real-server test instructions.
The PHP worker needs read access to framework and extensions, and write access to storage/. Only the operator performing an update needs write access to framework files. Use HTTPS, back up data, and keep config/local.php out of version control.
For a bootstrap ZIP including the starter theme and providers, run php core/bin/console.php package --full. A normal core release contains only managed framework files.
Deploy at the domain root, with PHP 8.3+ for both CLI and web workers. In CloudPanel, exclude /assets/ from the generic static-file regex with ^(?!/assets/) so theme assets reach PHP; they live outside public/. CORS and HTTP/3 headers are separate hosting settings. Verify both frontend and backend routing. Restart PHP-FPM or Apache PHP workers after an update to clear their OPcache; a CLI opcache_reset() does not clear the web-worker cache.
New Starter sites begin with indexable set to false in site/meta.php. Set it to true when ready to launch, then check deployed robots directives. Custom themes own their indexing behavior. Core does not generate robots.txt, a sitemap, or canonical URLs automatically.
Quality and security
Templates must escape untrusted output, and SQLite queries are parameterized. Asset routes are confined to the selected theme and approved file types. The minimal Starter uses system fonts, a shared layout, reusable components, visible keyboard focus, a skip link, and responsive layouts; it works without JavaScript. Accessibility and interaction in a custom theme remain the site’s responsibility.
php core/tests/run.php
php site/tests/run.phpFramework checks use independent fixtures; keep website-specific checks in site/tests/run.php and adapt them to your site. Run session-based contact checks in a subprocess or HTTP fixture before printed progress can interfere with headers. Coverage includes typed entity queries, page routing, response headers, templates, assets, queue retention, archive integrity and rollback. The optional Docker hosting suite checks Apache and nginx/PHP-FPM; see core/docs/deployment.md. WCAG 2.2 AA is the target; a full assistive-technology audit remains to be done.
Security headers and external embeds.
Responses default to nosniff, strict-origin-when-cross-origin and a Content Security Policy restricted to same-origin resources, with data: images allowed and framing by other sites blocked. Explicit response headers override defaults regardless of header-name case. To allow an embed, copy the full default CSP and extend only the necessary directive on that one response, for example frame-src for one trusted origin. A custom CSP replaces the entire default policy. Avoid wildcards, unsafe-inline and unsafe-eval; account for external visitor requests in your privacy and consent choices. Response::DEFAULT_HEADERS and emittedHeaders() expose the defaults and emitted header set for tests.
Read the security header and CSP examplesStatus and roadmap
Routing and responses with explicit page paths and slash redirects; request context and opt-in POST; plugin contracts, hooks and console commands; SQLite settings, pages, Entities CRUD, typed queries and explicit indexes; themes and nested components; versioned assets; SMTP with optional Reply-To, aggregate analytics and a durable queue; a copyable queued contact form with token recovery and configurable retries; private queue monitoring and completed-job retention; reversible core updates and independent framework checks.
MariaDB / PostgreSQL adapters and data transfer; separate extension updates; signed online updates; admin and content editing; authentication; a general form builder and uploads.