Configuration Reference¶

Teyaotlani servers can be configured using a TOML file. This reference documents all available configuration options.

Using a configuration file¶

Create a config.toml file and use it with the CLI or Python API:

CLIPython

teyaotlani serve --config config.toml

from teyaotlani import ServerConfig, run_server

config = ServerConfig.from_toml("config.toml")
await run_server(config)

Configuration Sections¶

[server]¶

Core server settings.

Key	Type	Default	Description
`host`	string	`"localhost"`	Server host address to bind to
`port`	integer	`300`	Server port (default is Spartan's standard port)
`document_root`	string	`"./capsule"`	Path to serve files from
`max_file_size`	integer	`104857600`	Maximum file size to serve in bytes (100 MB)
`enable_directory_listing`	boolean	`false`	Enable automatic directory listings
`index_files`	array	`["index.gmi", "index.gemini"]`	Files to look for as directory index

Example¶

[server]
host = "0.0.0.0"
port = 300
document_root = "./public"
max_file_size = 52428800  # 50 MB
enable_directory_listing = true
index_files = ["index.gmi", "index.gemini", "index.txt"]

[rate_limit]¶

Rate limiting to prevent abuse and DoS attacks.

Key	Type	Default	Description
`enabled`	boolean	`true`	Enable rate limiting
`capacity`	integer	`10`	Maximum burst capacity (token bucket)
`refill_rate`	float	`1.0`	Tokens added per second
`retry_after`	integer	`30`	Suggested retry delay for limited clients (seconds)

Example¶

[rate_limit]
enabled = true
capacity = 20
refill_rate = 2.0
retry_after = 60

[access_control]¶

IP-based access control using allow/deny lists.

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable IP-based access control
`allow_list`	array	`[]`	CIDR ranges to allow
`deny_list`	array	`[]`	CIDR ranges to deny (checked first)
`default_allow`	boolean	`true`	Allow IPs not in any list

Order of evaluation

Deny list is checked first
Allow list is checked second
If no match, default_allow is used

Example¶

[access_control]
enabled = true
allow_list = ["192.168.1.0/24", "10.0.0.0/8"]
deny_list = ["192.168.1.100/32"]
default_allow = false

[upload]¶

File upload handling configuration.

Key	Type	Default	Description
`enabled`	boolean	`false`	Enable file uploads
`upload_dir`	string		Directory to store uploaded files
`max_upload_size`	integer	`10485760`	Maximum upload size in bytes (10 MB)
`enable_delete`	boolean	`false`	Allow deletions via zero-byte upload

Example¶

[upload]
enabled = true
upload_dir = "./uploads"
max_upload_size = 5242880  # 5 MB
enable_delete = true

[logging]¶

Logging configuration.

Key	Type	Default	Description
`level`	string	`"INFO"`	Log level: DEBUG, INFO, WARNING, ERROR
`hash_ips`	boolean	`true`	Hash client IPs in logs for privacy
`json`	boolean	`false`	Output logs in JSON format

Example¶

[logging]
level = "DEBUG"
hash_ips = false
json = true

Complete Example¶

Here's a complete configuration file with all options:

# Teyaotlani Spartan Server Configuration

[server]
host = "0.0.0.0"
port = 300
document_root = "./capsule"
max_file_size = 104857600
enable_directory_listing = true
index_files = ["index.gmi", "index.gemini"]

[rate_limit]
enabled = true
capacity = 10
refill_rate = 1.0
retry_after = 30

[access_control]
enabled = false
# allow_list = ["192.168.1.0/24"]
# deny_list = ["192.168.1.100/32"]
default_allow = true

[upload]
enabled = false
# upload_dir = "./uploads"
max_upload_size = 10485760
enable_delete = false

[logging]
level = "INFO"
hash_ips = true
json = false