Basehim

The CMS built for the AI era. An open-source, API-first PHP CMS with a built-in Model Context Protocol server, so AI agents can search, read and draft your content — every permission scoped, so you decide exactly what they reach.

No Composer. No build step. No daemons. No public/ directory. Upload the files, open your site, and the installer takes it from there.

basehim.com · Docs · API reference · Getting started · Download

Quick start

On a web host — download basehim.zip, upload the contents of its basehim/ folder to public_html/ (or any subfolder), and open the site. The installer asks for your database details.

On your machine — PHP 8.1+ and a MySQL or MariaDB database:

curl -L -o basehim.zip https://github.com/basehim/basehim/releases/latest/download/basehim.zip
unzip basehim.zip && cd basehim
php -S localhost:8000 server.php     # then open http://localhost:8000

Or from source: git clone https://github.com/basehim/basehim.git && cd basehim and the same php -S line.

No database handy? One container is enough:

docker run -d --name basehim-db -p 3306:3306 \
  -e MARIADB_ROOT_PASSWORD=secret -e MARIADB_DATABASE=basehim mariadb:11
# installer: host 127.0.0.1, database basehim, user root, password secret

server.php is for local development only. On a real host Apache uses the bundled .htaccess, and server.php answers 404 to anything else.

---

Why Basehim

Most modern CMSs assume SSH, Composer and a deploy pipeline. Basehim assumes the hosting real clients actually buy — cPanel, Plesk, plain Apache — and still gives you a first-class API surface and native agent support.

• AI-ready by default — a built-in MCP server at /mcp. Point Claude, or any MCP client, at your site and it registers itself. No client id, no secret.
• Scoped, revocable access — agents get OAuth 2.1 tokens carrying explicit scopes. A token issued to read posts cannot touch users.
• API-first — a full REST API over posts, pages, media, taxonomies, menus, comments, users and settings.
• Zero-build deployment — pure PHP. Upload a zip, run the installer.
• Apps and themes — drop a folder in, activate, done. Marketplace built in, every download checksum-verified.
• A readable micro-framework — autoloader, DI container with autowiring, router, view engine, hooks/events, JWT, CSRF, sessions, file cache.

AI and agents

This is the part worth reading first.

MCP server

Basehim exposes a Model Context Protocol endpoint at the root of your domain:

| Method | Path | Purpose | | ------ | ------ | ------------------------------------------------ | | GET | /mcp | Discovery — transport, auth methods, metadata URL | | POST | /mcp | JSON-RPC 2.0 endpoint |

Add https://your-site.com/mcp as a custom connector in an AI assistant and it handles registration itself. The endpoint accepts either an OAuth token or a bearer API key.

Resources are addressed with a basehim:// URI scheme — basehim://site/info, basehim://post/{id-or-slug} — and are enumerated through resources/list.

OAuth 2.1 — built for agents, not humans clicking through consoles

Agent auth sits at the domain root, outside /api/v1:

| Method | Path | Purpose | | ------------ | ------------------------------------------- | ------------------------------ | | GET | /.well-known/oauth-protected-resource | Resource metadata (RFC 9728) | | GET | /.well-known/oauth-protected-resource/mcp | Path-suffixed variant | | GET | /.well-known/oauth-authorization-server | Server metadata (RFC 8414) | | GET | /.well-known/openid-configuration | Same metadata, OIDC path | | POST | /oauth/register | Dynamic client registration | | GET/POST | /oauth/authorize | Consent screen and approval | | POST | /oauth/token | Exchange a code, or refresh |

Grants: authorization_code and refresh_token, with PKCE (S256).

Dynamic client registration is the point — there is nothing to configure by hand before an agent can connect.

Scopes

Every token carries scopes, and a token issued for one thing cannot do another:

posts:read        posts:write
taxonomies:read   taxonomies:write
media:read        comments:read      comments:write
settings:read     users:read

Installed apps can contribute their own scopes, so your site's list may be longer. Whatever your site advertises is authoritative — fetch /.well-known/oauth-authorization-server to see it.

A token also acts as the account behind it: scopes choose the tools, and the account's role decides what those tools may do, exactly as on the REST API. An author's posts:write token edits that author's posts and no one else's, a contributor's goes in for review rather than live, and suspending an account stops its tokens and keys at once. Scopes added by apps are granted only to administrators unless the app maps them to a capability with the mcp.scope_capabilities filter.

Desktop agent API

For companion apps running on a machine rather than in a chat window:

Token hygiene

A token is a password. Issue the narrowest scope that does the job, use a separate token per integration so one can be revoked without disturbing the others, and keep tokens out of client-side code and screenshots. Revoking in the admin takes effect immediately.

REST API

Base URL https://your-site.com/api/v1.

• Success responses are wrapped: {"data": …}
• Errors follow RFC 7807 problem details: {"type", "title", "status", "detail"}
• Single items are fetched by slug; updates and deletes address them by id. GET /posts/hello-world but DELETE /posts/12. This catches people out.
• List endpoints accept page, per_page, status, q and author_id.

Reading published content needs no authentication. Anything that writes, or reads drafts, does.

# Public read — no auth
curl https://your-site.com/api/v1/posts

# API key
curl -H "Authorization: Bearer basehim_…" https://your-site.com/api/v1/me

# JWT
curl -X POST https://your-site.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"…"}'

# Create a post
curl -X POST https://your-site.com/api/v1/posts \
  -H "Authorization: Bearer basehim_…" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello","content":"<p>World</p>","status":"published"}'

Three ways in, for three different callers:

| Method | Header / flow | Best for | |---|---|---| | API key | Authorization: Bearer basehim_… | Scripts, server-to-server | | JWT | POST /auth/login, refresh at /auth/refresh | Apps acting for a signed-in person | | OAuth 2.1 | Dynamic client registration | AI agents over MCP |

The full endpoint list — content, media, taxonomies, comments, menus, users, settings, apps, cache and scheduling — is at basehim.com/docs/api-reference, and mirrored in the admin at /admin/api/reference.

Requirements

• PHP 8.1+ with pdo_mysql, mbstring, openssl, fileinfo, gd, zip
• MySQL 5.7+ or MariaDB 10.3+
• Apache or LiteSpeed with mod_rewrite (works on default cPanel). nginx works too, but you must replicate the .htaccess rules yourself — see Security.
• For local development, PHP's built-in server with server.php is enough
• ~30 MB disk, plus space for uploads

Install

1. Upload the contents of the basehim/ folder from basehim.zip (or of this repository) to your document root, e.g. public_html/.
2. Create a MySQL database and grant a user full privileges.
3. Visit your domain — you'll be redirected to /install.php.
4. Work through the wizard: database, site details, admin account, optional starter content.
5. That's it. The installer locks itself when it finishes (INSTALLED=true in .env); deleting install.php afterwards is optional.

Log in at /admin/login.

<details> <summary>Manual install</summary>

rsync -avz basehim/ user@server:/path/to/webroot/

cp .env.example .env
# Edit DB_*, APP_URL, then generate the two secrets:
php -r "echo 'APP_KEY=' . bin2hex(random_bytes(16)) . PHP_EOL;"
php -r "echo 'JWT_SECRET=' . bin2hex(random_bytes(32)) . PHP_EOL;"

# Migrations apply in filename order
for f in database/migrations/*.sql; do mysql -u user -p mydb < "$f"; done

chmod -R 775 storage/ content/

Generate a password hash with:

php -r "echo password_hash('YourPassword', PASSWORD_BCRYPT, ['cost' => 12]) . PHP_EOL;"

</details>

Subdirectory installs work out of the box — Basehim detects its own base path.

DB_PREFIX lets several sites share one database, which matters on shared hosting where you get a fixed number. Set it before installing and leave it alone afterwards.

Directory map

basehim/
├── index.php              # Front controller (all requests funnel here)
├── install.php            # Web installer (locks itself when done)
├── server.php             # Router for `php -S` — local development only
├── bootstrap.php          # Autoloader, env, sessions, boots the app
├── .htaccess              # Apache rewrites + security headers
├── .env                   # Your environment — git-ignored, NEVER commit
├── .env.example           # Template to copy to .env
│
├── app/
│   ├── Core/              # Router, Container, View, Cache, JWT, App base class
│   ├── Http/
│   │   ├── Controllers/   # Admin/, Api/, Web/
│   │   └── Middleware/    # Authenticate, CheckCapability, Cors
│   ├── Repositories/      # DB access layer (PDO)
│   └── Services/          # Business logic (PostService, AppService, …)
│
├── admin/views/           # Admin UI templates (Tailwind)
├── api/v1/                # REST API entry
├── config/                # app, database, auth, capabilities, cms
├── content/
│   ├── apps/              # Drop-in apps (manifest in app.json)
│   ├── themes/            # Drop-in themes (manifest in theme.json)
│   └── uploads/           # Media library
├── database/migrations/   # SQL migrations, applied in filename order
├── docs/                  # App, permission, and agent API guides
├── routes/                # api.php, admin.php, web.php
└── storage/               # Runtime: cache/, logs/, sessions/ (must be writable)

Everything under storage/ and content/uploads/ is runtime state — the directories are tracked, their contents are git-ignored.

Apps

An app is a folder in content/apps/ with an app.json manifest. Install by uploading a zip from /admin/apps, from the built-in marketplace, or by dropping the folder in — it is auto-detected.

content/apps/my-app/
├── app.json                 # Manifest (required)
├── src/
│   └── App.php              # Entry class extending App\Core\App
├── views/                   # (optional) app-owned templates
└── assets/                  # (optional) bundled css/js/images

app.json

{
    "name": "My App",
    "vendor": "myco",
    "slug": "my-app",