Configuration

The server reads its configuration from environment variables only, each prefixed PITWALL_: there are no configuration files and no flags. It checks every value when it starts and refuses to start on one that is invalid, saying which; an error never repeats a value that may hold a credential.

A runner is configured when it registers: the flags of pitwall-runner register, written to ~/.config/pitwall-runner/config.json. It reads one variable of its own.

Filter settings/

All 24Server 15Runner 9Required 4

Showing 24 of 24

Name	Type	Default	Required	Description
Server
#PITWALL_DATABASE_URL	urlsecret	—	required	The PostgreSQL connection URL, postgres://….
#PITWALL_HTTP_ADDR	host:port	:8080	—	The address the server listens on.
#PITWALL_DB_MAX_CONNS	int	10	—	Size of the database connection pool, 1 to 1000.
#PITWALL_PUBLIC_URL	url	unset	with Telegram	The address people reach the instance at, such as https://pitwall.example.com, with no trailing slash. Used in every link a notification carries and in the password reset link core user reset prints.
Proxy and HTTPS
#PITWALL_COOKIE_SECURE	bool	false	—	false marks the session cookie Secure when the request is HTTPS. true marks it always, for an instance only ever reached over HTTPS: signing in over plain HTTP then stops working.
#PITWALL_TRUSTED_PROXIES	list	empty	—	Comma-separated addresses and CIDR ranges whose X-Forwarded-For and X-Forwarded-Proto the server believes. List the address the server sees the proxy connect from, which behind Docker’s networking may not be the proxy’s own.
GitHub
#PITWALL_GITHUB_APP_ID	int	unset	with the key	The numeric id of the instance’s GitHub App, never its client id. Set it with the private key or not at all: with neither, GitHub is off; with only one, the server refuses to start.
#PITWALL_GITHUB_APP_PRIVATE_KEY	pemsecret	unset	with the id	The GitHub App’s private key, a PEM RSA key. Accepted with real line breaks or with each written as \n.
#PITWALL_MIRROR_DIR	path	unset	—	Where the server keeps its read-only mirror of each repository; the image sets /var/lib/pitwall/mirror. The mirror is on only with this and the GitHub App. Mount a named volume there: the image runs as user 65532, which must be able to write to it. The mirror is a cache and can be deleted.
Pipeline
#PITWALL_TICKET_TOKEN_BUDGET	int	2000000	—	Tokens one pipeline run may spend before it blocks: input, output and cache creation, never cache reads. Applies to runs started after the change.
#PITWALL_MILESTONE_TOKEN_BUDGET	int	12000000	—	Tokens one milestone’s run may spend before it blocks, counted as a ticket’s are. Larger than a ticket’s, since every phase goes through the agents. Applies to runs started after the change.
Retention
#PITWALL_THREAD_RETENTION_DAYS	int	7	—	Days an unsaved chat is kept after its last message, 1 to 365. A saved chat is kept.
#PITWALL_FILE_RETENTION_DAYS	int	365	—	Days an attached file keeps its contents, 0 for forever, up to 3650. Past it the ticket or chat says the file was removed.
Notifications
#PITWALL_TELEGRAM_BOT_TOKEN	stringsecret	unset	—	The token of the Telegram bot notifications go through. Unset, notifications are off. The bot must be this instance’s alone. Needs PITWALL_PUBLIC_URL.
Runner downloads
#PITWALL_RUNNER_DIST_DIR	path	unset	—	The directory of the runner binaries the server offers for download, named pitwall-runner-<os>-<arch>; the image sets /runner-dist. Unset, the download answers 404.
Runner
#PITWALL_RUNNER_CLAUDE_BIN	path	claude on PATH	—	Read by the runner, not the server: the Claude Code CLI to run instead of the one found on PATH or where its installers put it.
#--core-url	url	—	required	The address of the server. The runner opens every connection to it.
#--token	stringsecret	—	required	The registration token from Runners → Register runner, used once. The runner exchanges it for a credential of its own.
#--name	string	—	required	The runner’s name, shown on the Runners page and on the work it does.
#--labels	list	none	—	Comma-separated labels, such as linux or macos,xcode. A runner takes jobs whose project needs only labels it has.
#--capacity	int	1	—	Jobs this runner takes at once, 1 to 32.
#--sharing	enum	owner_only	—	owner_only takes only its owner’s work; owner_projects takes the work of any project its owner belongs to.
#--workspace	path	~/.local/share/pitwall-runner/workspace	—	Where the runner keeps its checkouts, one per project and repository, reused between jobs.
#--no-self-update	bool	false	—	Stops the runner from updating itself when the server’s build changes. Update it by hand instead.

Secrets

Three settings of the server hold secrets: PITWALL_DATABASE_URL, which carries the database password, PITWALL_GITHUB_APP_PRIVATE_KEY and PITWALL_TELEGRAM_BOT_TOKEN. Pass them to the server’s environment from your secret store; none belongs in a file in a repository. A runner’s registration token is used once and exchanged for a credential the runner keeps in its configuration file, readable by its user only.

Settings that are not here

A project’s own settings are not configuration. Its repositories, its build and test commands, the runner labels it needs and where it is tested by hand are fields of the project, changed by its owner.

Claude credentials are not configuration either. Each runner holds its owner’s Claude tokens, added with pitwall-runner claude-token add; the server never sees them.