# XBuckle

> No need to register for cloud services just to develop. Start a simulated stack on your machine, let agents auto-configure the app, then migrate smoothly to production. Real SDKs against loopback — not a hosted vendor, not full AWS/Supabase.

## Value

1. **No cloud signup maze** for local development
2. **Local simulated stack** — start services on your machine
3. **Agent auto-config** — Connect prompt / MCP for env + wiring
4. **Smooth production migration** — same SDK shape; swap endpoints and secrets when shipping

## Humans (install first)

1. Download the macOS app from GitHub Releases: https://github.com/21stware/xbuckle/releases
2. Open XBuckle → create or open a project → start services (no cloud accounts required)
3. Open Connect → copy the prompt into your app env, or let an agent apply it
4. Ports are **per project** — always use Connect / current project values, not hardcoded defaults
5. For production, point the same SDKs at real cloud endpoints — do not bake loopback into release builds

Canonical site: https://21stware.github.io/xbuckle/

## Docs (customer)

- [Product](https://21stware.github.io/xbuckle/guide/what-is-xbuckle)
- [Get started](https://21stware.github.io/xbuckle/guide/quickstart)
- [Desktop app](https://21stware.github.io/xbuckle/guide/desktop)
- [Ports](https://21stware.github.io/xbuckle/guide/ports)
- [Use](https://21stware.github.io/xbuckle/humans/)
- [Connect / Ship](https://21stware.github.io/xbuckle/humans/connect-ship)
- [Service limits](https://21stware.github.io/xbuckle/reference/services)
- [Project files](https://21stware.github.io/xbuckle/reference/xbujson)

## Docs (agents)

- [Agents overview](https://21stware.github.io/xbuckle/agents/)
- [MCP](https://21stware.github.io/xbuckle/agents/mcp)
- [Workflow](https://21stware.github.io/xbuckle/agents/workflow)
- [Prompt snippet](https://21stware.github.io/xbuckle/agents/prompt)
- [Full text](https://21stware.github.io/xbuckle/llms-full.txt)

## Ports (per project)

Stored on each project as `ports.{proxy,mcp,pg,redis,smtp}`. Defaults when not customized:

- HTTP: http://127.0.0.1:3100
- MCP: http://127.0.0.1:3101
- Postgres: postgresql://postgres:postgres@127.0.0.1:5432/postgres?sslmode=disable
- Redis: redis://127.0.0.1:6379
- SMTP: 127.0.0.1:1025
- Local keys: `xbuckle-anon-key` / `xbuckle-service-role-key` (loopback only)

## Agent rules

1. Use real SDKs against loopback only.
2. App DB via the project's pg port, not control-plane `POST /db`.
3. Run MCP `runtime.selftest` before claiming integration works.
4. Never send destructive traffic to production clouds unless a human explicitly asks.
5. Treat mocks as honest subsets — read service limits when unsure.
6. Project config is the `.xbuj` document; data lives in sibling `.xbujd/`.

## Optional

- [GitHub](https://github.com/21stware/xbuckle)
- [@xbuckle/config](https://www.npmjs.com/package/@xbuckle/config) — build/parse project files