Configuration

All behaviour lives in config/truss.php. Publish it with:

php artisan vendor:publish --tag=truss-config

Every key has a sensible default and, where relevant, an env() override.

Reference

Key	Env	Default	Purpose
route_prefix	TRUSS_ROUTE_PREFIX	truss	URL prefix for the page and the JSON / asset routes
enabled	TRUSS_ENABLED	local only	Global on/off switch. Off means the routes 404
middleware		['web']	Auth-context middleware so the gate can see the user
authorization.allowed_emails	TRUSS_ALLOWED_EMAILS	[]	Emails the default gate admits in non-local (comma-separated)
cache.ttl	TRUSS_CACHE_TTL	3600	Seconds a schema snapshot is cached
connections		[]	Which DB connections are visualizable (defaults to the app’s default)
excluded_tables		framework tables	Tables filtered out server-side, never sent to the browser
annotations.source		['config', 'database']	Ordered precedence for resolving an annotation; first match wins
annotations.notes		[]	Global notes rendered in a header block by the formats that have one
annotations.tables		[]	Per-table annotations, keyed by table name
annotations.columns		[]	Per-column annotations, keyed by table.column
export.default_format	TRUSS_EXPORT_FORMAT	dbml	Format truss:export and the facade use when none is given
mcp.enabled	TRUSS_MCP_ENABLED	true	Register the MCP server when laravel/mcp is installed
diagram.type_labels	TRUSS_TYPE_LABELS	native	Default column-type labels: native or laravel
diagram.mermaid_url	TRUSS_MERMAID_URL	null	Where to load Mermaid from. Null self-hosts (no CDN)
diagram.min_zoom	TRUSS_MIN_ZOOM	0.7	Readable floor for auto-fit. The Fit button ignores it
theme.colors		[]	Custom colour overrides by semantic knob, under light and dark
theme.fonts.mono	TRUSS_THEME_FONT_MONO	null	Monospace font family (also drives the diagram text)
theme.fonts.sans	TRUSS_THEME_FONT_SANS	null	Sans-serif font family
focus.default_depth	TRUSS_FOCUS_DEPTH	1	Foreign-key neighbour depth when focusing a table
large_schema.warn_above	TRUSS_LARGE_SCHEMA_WARN_ABOVE	60	Table count above which a “large schema” hint is shown
diff.enabled	TRUSS_DIFF_ENABLED	true	Schema diff master switch. Off writes nothing to disk and hides the feature
diff.disk	TRUSS_DIFF_DISK	local	Disk the diff baseline file is written to. Deliberately not your application’s default disk
doctor.preset	TRUSS_DOCTOR_PRESET	recommended	Which rules run: recommended (high-confidence), strict (all), none
doctor.rules		[]	Per-rule overrides by code: false disables, true enables, ['severity' => '...'] re-severities
doctor.ignore		[]	Per-rule fnmatch patterns (table or table.column) to silence
doctor.fail_on	TRUSS_DOCTOR_FAIL_ON	error	Severity at or above which truss:doctor exits non-zero
doctor.exclude		[]	Extra tables to skip, on top of excluded_tables
doctor.dashboard	TRUSS_DOCTOR_DASHBOARD	true	Show the doctor findings in the dashboard “Health” panel
doctor.flag_tables	TRUSS_DOCTOR_FLAG_TABLES	true	Badge tables with findings on the diagram even when the panel is closed

Notes on individual keys

enabled and middleware

These, together with the viewTruss gate, control access. See the Authorization guide.

connections

Leave empty to use the application’s default connection. To visualize specific connections, list them:

'connections' => [
    'mysql' => [],
    'reporting' => ['excluded_tables' => ['legacy_import']],
],

Only listed connections are visualizable; a request for any other connection returns 404. Per-connection excluded_tables are merged on top of the global list.

excluded_tables

Applied server-side at serve time, so their structure never reaches the browser and toggling the list needs no rebuild. The defaults cover framework and infrastructure tables (migrations, password_reset_tokens, sessions, cache, cache_locks, jobs, job_batches, failed_jobs).

diagram.type_labels

native shows the exact database type (varchar(255), bigint unsigned), which is the source of truth. laravel shows a best-effort short label (string, integer), computed in the browser. The mode is also toggleable live in the UI; this key sets the default.

diagram.mermaid_url

Null (the default) self-hosts Mermaid from the package, so no CDN is contacted. Set a URL to load Mermaid from a CDN or your own copy instead.

diagram.min_zoom

The lowest zoom the automatic fit will use, so a large schema stays legible and you pan around it rather than being dumped into an unreadable overview. The Fit button ignores this floor.

theme.*

Redefine the dashboard’s colours and fonts to match your app. theme.colors takes a small set of semantic knobs (accent, accent-secondary, background, surface, surface-alt, text, muted, border) under light and dark; only the knobs you set are overridden, so a handful of values re-skins the whole dashboard in both modes. theme.fonts.mono and theme.fonts.sans take font-family names only (a font your app already loads or a system font). The overrides are served as a same-origin stylesheet, linked only when a theme is configured, so a default install makes no extra request and a strict CSP still needs only style-src 'self'. Every value is validated before it is emitted, so an invalid value falls back to the default. See the Theming guide.

annotations.*

Declare the business meaning a type cannot carry, so it renders into the exports and the MCP tools. annotations.source is an ordered list, resolved first match wins: config reads the maps below, database reads native table and column comments (MySQL, MariaDB, and Postgres; SQLite and SQL Server have none and are skipped). Drop database to ignore comments. annotations.notes are global notes, annotations.tables is keyed by table name, and annotations.columns by table.column. A comment is part of the CREATE TABLE definition, not row content, so reading it stays structure only. See Truss as AI context.

export.default_format

The format truss:export and the Truss facade use when none is given, one of dbml, json, csv, markdown, mermaid, or llm. Defaults to dbml, a standard other tools already read.

mcp.enabled

Master switch for the optional MCP server. It has no effect unless the optional laravel/mcp package is installed, so a host that does not opt in is unaffected; when the package is present, the server registers unless this is false.

diff.enabled and diff.disk

Control the schema diff feature. diff.enabled (default true) is the master switch: when false, no baseline is captured, nothing is written to disk, the dashboard “Changes” button is hidden, and truss:diff reports the feature is off. The check runs before any filesystem access, so it is a hard guarantee that Truss will not touch your disk. diff.disk chooses the filesystem disk the baseline is written to, local by default; the path is always truss/baselines/{connection}.json. It does not follow your application’s default disk on purpose: the baseline is derived tooling state, not application data, so it should not land in a production bucket. If the disk cannot be read, the diff is unavailable and says so, and nothing else about Truss is affected. See the Schema diff guide.

doctor.*

Control the schema doctor. doctor.preset picks which rules run (recommended runs high-confidence rules only, strict runs everything, none runs nothing but what you enable). doctor.rules overrides individual rules by code (disable, enable a heuristic, or change a severity), and doctor.ignore silences known cases with fnmatch patterns on a table or table.column. doctor.fail_on sets the severity at or above which truss:doctor exits non-zero, and doctor.exclude adds tables to skip on top of excluded_tables. The last two are the dashboard side: doctor.dashboard shows the “Health” panel (when false, the dashboard receives no findings and the CLI is untouched), and doctor.flag_tables badges tables with findings on the diagram even when the panel is closed.

Content-Security-Policy

Truss serves its JavaScript, CSS, a vendored copy of Mermaid, and the IBM Plex Mono font from a gated route inside the package. No CDN is used by default. Under a strict CSP, the following cover Truss’s own assets:

script-src 'self';
style-src 'self' 'unsafe-inline';
font-src 'self';

style-src needs 'unsafe-inline' because Mermaid injects styles into the rendered SVG at runtime. To load Mermaid from a CDN instead, set TRUSS_MERMAID_URL and adjust script-src accordingly.