name

trailbase

description

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.

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.

TrailBase

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.