Configuration Reference

SDK configuration

`createGunsoleClient(config)`

Option	Type	Default	Required	Description
`projectId`	`string`	—	Yes	Project identifier, auto-creates in desktop app
`apiKey`	`string`	—	No	API key (required for cloud mode, any string for local)
`mode`	`"local" \| "desktop" \| "cloud"`	—	Yes	Determines endpoint URL
`endpoint`	`string`	—	No	Override endpoint URL
`env`	`string`	—	No	Environment label
`appName`	`string`	—	No	Application name
`appVersion`	`string`	—	No	Application version
`defaultTags`	`Record<string, string>`	`{}`	No	Tags merged into every log
`batchSize`	`number`	`10`	No	Logs before auto-flush
`flushInterval`	`number`	`5000`	No	Auto-flush interval (ms)
`fetch`	`function`	`globalThis.fetch`	No	Custom fetch implementation
`isDebug`	`boolean`	`false`	No	Disables gzip compression
`buckets`	`string[]`	—	No	Typed bucket accessors with autocomplete

Endpoint modes

Mode	URL
`local`	`http://localhost:17655`
`desktop`	`http://localhost:8787`
`cloud`	`https://api.gunsole.com`

Log entry fields

`LogOptions` (what you pass to `gun.info()`, etc.)

Field	Type	Required	Description
`message`	`string`	Yes	Human-readable log message
`bucket`	`string`	Yes	Category name (auto-created)
`context`	`Record<string, unknown>`	No	Arbitrary structured data
`tags`	`Partial<Tags> \| TagEntry<Tags>[]`	No	Filterable key-value pairs
`traceId`	`string`	No	Links related log entries

`BucketLogOptions` (what you pass to `gun.payment()`, etc.)

Field	Type	Required	Description
`context`	`Record<string, unknown>`	No	Arbitrary structured data
`tags`	`Partial<Tags> \| TagEntry<Tags>[]`	No	Filterable key-value pairs
`traceId`	`string`	No	Links related log entries

Auto-populated fields

These are set automatically by the SDK and sent with every log:

Field	Source
`level`	Determined by method: `info()`, `debug()`, `warn()`, `error()`
`timestamp`	`Date.now()` (unix milliseconds)
`userId`	From `gun.setUser({ id: "..." })`
`sessionId`	From `gun.setSessionId("...")`
`env`	From config
`appName`	From config
`appVersion`	From config

Reserved names

Reserved bucket names

Cannot be used with buckets config option:

log, info, debug, warn, error, setUser, setSessionId, flush, destroy, attachGlobalErrorHandlers, detachGlobalErrorHandlers

Reserved tag keys

Cannot be used as tag schema keys:

bucket, message, level, timestamp, userId, sessionId, env, appName, appVersion

TypeScript exports

Runtime

Export	Description
`createGunsoleClient`	Factory function to create client
`GunsoleClient`	Client class

Types

Export	Description
`GunsoleClientConfig`	Configuration options
`LogEntry`	Log entry structure
`LogLevel`	`"info" \| "debug" \| "warn" \| "error"`
`LogOptions`	Options passed to log methods
`TagEntry`	Single-key tag entry type
`UserInfo`	User information
`ClientMode`	`"cloud" \| "desktop" \| "local"`
`BucketLogOptions`	Log options for bucket methods (no bucket/message)
`BucketLogger`	Callable bucket accessor interface
`WithBuckets`	Mapped type adding bucket accessors to client
`ReservedBucketName`	Union of reserved bucket names
`ValidateBuckets`	Compile-time bucket name validator
`ReservedTagKey`	Union of reserved tag keys
`ValidTagSchema`	Compile-time tag schema constraint

TypeScript requirements

TypeScript 5.0+ required for const generic inference (bucket literal types)
TypeScript 5.4+ recommended for NoInfer (bucket name compile-time validation)
Target: ES2020

Desktop app settings

Project settings

Setting	Default	Description
Log retention (days)	Unlimited	Auto-delete logs older than N days
Auto-delete old logs	Off	Enable/disable retention enforcement

Bucket settings

Setting	Default	Description
Log retention (days)	Inherits project	Override project retention per bucket

App preferences

Setting	Options	Description
Theme	Light / Dark / Auto	UI color scheme

HTTP server

Setting	Value
Default port	`17655`
Host	`localhost` only
CORS	Enabled (all origins)
Compression	gzip accepted on request body

Internal constants

These are compiled into the desktop app and not user-configurable:

Constant	Value	Description
Log batch size	50	Max logs per flush to DB
Batch interval	100ms	Max time between DB flushes
Frontend buffer	~2000 logs	Max in-memory logs in viewer
New log animation	3 seconds	Green fade duration for new entries

Database

Setting	Value
Engine	SQLite (WAL mode)
Location (macOS)	`~/Library/Application Support/gunsole/gunsole.db`
Location (Linux)	`~/.local/share/gunsole/gunsole.db`
Location (Windows)	`%APPDATA%\gunsole\gunsole.db`
Tables	workspaces, projects, buckets, filters, logs, tags, log_tag_map, app_preferences
Foreign keys	Enabled
Migrations	Auto-run on startup