TrailBase
Use this skill to work with TrailBase as an application platform: install it, start it, configure traildepot, expose data through Record APIs, call HTTP APIs directly, or integrate a first-party SDK.
Prefer current repo files over memory. If the user asks about the public/latest release, package version, Docker tag, or external docs, verify online or from the package registry before giving version-specific advice.
Workflow
- Identify the task surface:
- Install/run/deploy: read
references/install-run.md.
config.textproto, migrations, Record API setup, ACLs: read references/config-and-migrations.md.- Direct HTTP/Auth/Record API calls: read
references/http-api.md.
- OAuth, OIDC, PKCE, or "TrailBase as SSO" questions: read
references/oauth-sso.md.
- SDK integration: read
references/sdk.md, then inspect the language-specific client source if precision matters.
- WASM custom endpoints: read
references/custom-wasm-apis.md.
- Repo navigation or implementation changes: read
references/source-map.md.
- Verify against source for nontrivial answers. TrailBase has generated docs and multiple clients; source can drift from docs.
- For code examples, use localhost
http://localhost:4000 unless the user gives another base URL.
- For auth-sensitive examples, never invent tokens. Show placeholders such as
${AUTH_TOKEN} or obtain tokens from a real login command if credentials are provided.
Core Facts
- TrailBase is a single executable named
trail; trail run starts a local server on localhost:4000 and bootstraps ./traildepot.
- Admin UI is at
/_/admin/; optional auth UI is added with trail components add trailbase/auth_ui and then lives under /_/auth/login.
- Record APIs expose
STRICT SQLite TABLEs or VIEWs with an INTEGER, UUIDv4, or UUIDv7 primary key.
- Main public Record API path is
/api/records/v1/<api-name>.
- Main auth path is
/api/auth/v1.
- Auth tokens are sent with
Authorization: Bearer <auth_token>; refresh and CSRF tokens may also be represented as Refresh-Token and CSRF-Token headers by SDKs.
- TrailBase can broker sign-in through configured external OAuth/OIDC providers and supports an auth-code + PKCE handoff to native or different-origin apps. Do not describe it as a full OAuth/OIDC identity provider unless the current source has added standard IdP endpoints such as authorization, discovery, JWKS, and userinfo.
- Realtime subscriptions are exposed under
/api/records/v1/<api-name>/subscribe/<id-or-*>.
Validation
When changing a TrailBase repo checkout, prefer focused validation:
cargo test -p trailbase-client
pnpm --filter trailbase test
trail help
trail run
Pick commands that match the files touched. If commands require missing dependencies, report the exact blocker and still provide source-backed reasoning.
1---2name: trailbase3description: TrailBase project guide for installing and running the single-executable backend, configuring traildepot/config.textproto and migrations, exposing Record APIs, using auth and token flows, integrating first-party SDKs for TypeScript/JavaScript, Dart/Flutter, Rust, C#/.NET, Swift, Kotlin, Go, and Python, calling HTTP APIs directly, implementing WASM custom endpoints, and locating relevant source/docs in the trailbase repository. Use when Codex needs to answer or implement TrailBase setup, SDK, REST/HTTP API, auth, realtime, configuration, migration, deployment, or custom endpoint work.4---56# TrailBase78Use this skill to work with TrailBase as an application platform: install it, start it, configure `traildepot`, expose data through Record APIs, call HTTP APIs directly, or integrate a first-party SDK.910Prefer current repo files over memory. If the user asks about the public/latest release, package version, Docker tag, or external docs, verify online or from the package registry before giving version-specific advice.1112## Workflow13141. Identify the task surface:15 - Install/run/deploy: read `references/install-run.md`.16 - `config.textproto`, migrations, Record API setup, ACLs: read `references/config-and-migrations.md`.17 - Direct HTTP/Auth/Record API calls: read `references/http-api.md`.18 - OAuth, OIDC, PKCE, or "TrailBase as SSO" questions: read `references/oauth-sso.md`.19 - SDK integration: read `references/sdk.md`, then inspect the language-specific client source if precision matters.20 - WASM custom endpoints: read `references/custom-wasm-apis.md`.21 - Repo navigation or implementation changes: read `references/source-map.md`.222. Verify against source for nontrivial answers. TrailBase has generated docs and multiple clients; source can drift from docs.233. For code examples, use localhost `http://localhost:4000` unless the user gives another base URL.244. For auth-sensitive examples, never invent tokens. Show placeholders such as `${AUTH_TOKEN}` or obtain tokens from a real login command if credentials are provided.2526## Core Facts2728- TrailBase is a single executable named `trail`; `trail run` starts a local server on `localhost:4000` and bootstraps `./traildepot`.29- Admin UI is at `/_/admin/`; optional auth UI is added with `trail components add trailbase/auth_ui` and then lives under `/_/auth/login`.30- Record APIs expose `STRICT` SQLite `TABLE`s or `VIEW`s with an `INTEGER`, UUIDv4, or UUIDv7 primary key.31- Main public Record API path is `/api/records/v1/<api-name>`.32- Main auth path is `/api/auth/v1`.33- Auth tokens are sent with `Authorization: Bearer <auth_token>`; refresh and CSRF tokens may also be represented as `Refresh-Token` and `CSRF-Token` headers by SDKs.34- TrailBase can broker sign-in through configured external OAuth/OIDC providers and supports an auth-code + PKCE handoff to native or different-origin apps. Do not describe it as a full OAuth/OIDC identity provider unless the current source has added standard IdP endpoints such as authorization, discovery, JWKS, and userinfo.35- Realtime subscriptions are exposed under `/api/records/v1/<api-name>/subscribe/<id-or-*>`.3637## Validation3839When changing a TrailBase repo checkout, prefer focused validation:4041```sh42cargo test -p trailbase-client43pnpm --filter trailbase test44trail help45trail run46```4748Pick commands that match the files touched. If commands require missing dependencies, report the exact blocker and still provide source-backed reasoning.
lollipopkit