Configuration

Configuration · [User+Dev]

Everything the cores do is configurable through options (Go) and, for a few things, the server config file and environment. This page is the reference for options, config files, directories, ports and database backends.

• Options at a glance
• Server options
• Client options
• The server config file
• The client config file
• Directories and environment
• Database backends
• In-memory mode

---

Options at a glance

Options are variadic and applied at New() (and, for some, at serve/connect time). Some can be set only once (marked below); the option's Go doc states this for each.

New behavior is expected to arrive as new Options rather than changes to the Server/Client types, so this list grows but the core signatures stay stable.

---

Server options

server.New("app", opts...) — from server/options.go:

Option	Once?	Purpose
WithInMemory()	yes	No filesystem: logs and sqlite DB run in memory. Errors on non-sqlite DBs.
WithDefaultPort(port uint16)	yes	Default daemon/listener port. Library default is 31416.
WithDatabase(db *gorm.DB)	yes	Use an existing gorm DB (auto-migrates users + certs).
WithDatabaseConfig(cfg *db.Config)	yes	Connect a DB from a config (sqlite/mysql/postgres).
WithHomeDirectory(path)	yes	App home dir (default ~/.app/); overridable by <APP>_ROOT_DIR.
WithTeamDirectory(name)	yes	Name of the server subdir (default teamserver; "" ⇒ none).
WithNoLogs(b bool)	yes	Disable all teamserver logging.
WithLogFile(path)	yes	Path of the server log file.
WithLogger(h slog.Handler)	yes	Replace console+file loggers with your handler (audit log unaffected).
WithConsoleOptions(func(*log.ConsoleOptions))	yes	Restyle the built-in console, keep core loggers.
WithLogFormat(log.Format)	yes	Console stream format: console/text/json.
WithHandler(h Handler)	no	Register a transport stack. First one becomes the default.
WithContinueOnError(b bool)	no	On persistent-listener start, keep going + join errors.

See Logging for the three logging options and Writing a Transport for WithHandler.

---

Client options

client.New("app", opts...) — from client/options.go:

Option	Once?	Purpose
WithInMemory()	yes	No filesystem: in-memory files for logging etc.
WithConfig(cfg *Config)		Use a specific remote-server config (skips disk lookup/prompt).
WithHomeDirectory(path)	yes	App home dir (default ~/.app/); overridable by <APP>_ROOT_DIR.
WithTeamDirectory(name)	yes	Name of the client subdir (default teamclient; "" ⇒ none).
WithNoLogs(b bool)	yes	Disable all teamclient logging.
WithLogFile(path)	yes	Path of the client log file.
WithLogger(h slog.Handler)	yes	Replace console+file loggers with your handler.
WithConsoleOptions(func(*log.ConsoleOptions))	yes	Restyle the built-in console.
WithLogFormat(log.Format)	yes	Console stream format.
WithDialer(d Dialer)	no	Transport backend. If it also implements team.Client, it becomes the query backend too.
WithTeamClient(c team.Client)	no	Set the Users/VersionServer backend explicitly (only when distinct from the dialer).
WithNoDisconnect()	yes	Keep the connection open across command runs (for closed-loop/console apps).

---

The server config file

Path: ~/.<app>/teamserver/configs/<app>.teamserver.json. Loaded on demand; if missing, the defaults are written. Struct (server/config.go):

{
  "daemon_mode": { "host": "", "port": 31416 },
  "log": {
    "level": 0,                    // slog level for the FILE logger (0 = Info)
    "grpc_unary_payloads": false,  // gRPC example: log unary payloads
    "grpc_stream_payloads": false, // gRPC example: log stream payloads
    "tls_key_logger": false        // dump TLS keys to file (debugging)
  },
  "listeners": [                   // persistent listeners, started by the daemon
    { "name": "gRPC", "host": "localhost", "port": 31337, "id": "..." }
  ]
}

Programmatic access: server.GetConfig(), server.SaveConfig(cfg), server.ConfigPath(). Persistent listeners are managed with ListenerAdd, ListenerRemove, ListenerStartPersistents (or the listen --persistent / close CLI commands).

---

The client config file

Path: ~/.<app>/teamclient/configs/<user>_<host>.teamclient.cfg. This is the connection file handed to operators — see Users & Authentication → The connection config file for the field-by-field breakdown. Managed with teamclient import or the client config API (GetConfigs, ReadConfig, SaveConfig, SelectConfig, Config).

---

Directories and environment

	Default	Configure
Home dir	~/.<app>/	WithHomeDirectory(path) or env <APP>_ROOT_DIR
Server subdir	teamserver/	WithTeamDirectory(name) ("" ⇒ use home dir directly)
Client subdir	teamclient/	WithTeamDirectory(name)

<APP> is the uppercased application name, e.g. CRACKER_ROOT_DIR. Subpaths (logs/, configs/, certs/) are fixed under the team dir. Accessors: HomeDir(), TeamDir(), LogsDir(), ConfigsDir(), CertificatesDir().

---

Database backends

The default is a file-based, pure-Go sqlite DB (or in-memory sqlite when WithInMemory()). It stores users and certificates. Swap it with WithDatabase (an existing *gorm.DB) or WithDatabaseConfig (a db.Config). Supported dialects: sqlite3, postgresql, mysql.

teamserver, _ := server.New("myapp", server.WithDatabaseConfig(&db.Config{
    Dialect:  db.Postgres,
    Database: "myapp",
    Host:     "localhost",
    Port:     5432,
    Username: "myapp",
    Password: "…",
}))

WithDatabase runs an automigration of the teamserver types (certificates and users). server.DatabaseConfig() reports the effective config (also shown in teamserver status).

Non-sqlite databases are assumed unable to run in memory, so combining them with WithInMemory() raises an error.

---

In-memory mode

WithInMemory() on either core redirects all filesystem interaction to an abstracted in-memory filesystem (log files, sqlite DB, etc.). The public API is unchanged, which makes it ideal for tests and for embedding a core you don't (yet) want touching disk. See Testing & In-Memory Use.

---

Related: Getting Started → · Logging →