Configuration
Every variable of the .env file of a self-hosted Skilder, its secrets, email, sign-in providers and the GitHub import token.
Pilot release. Self-hosting Skilder is a pilot.
A self-hosted Skilder is configured by one .env file next to its compose.yaml. docker compose reads it, and nothing else does. This page lists every variable of .env.example. The Quick start sets the required ones.
Edit the .env file
Compose expands $ and drops a # tail in a value. Single-quote a value that holds either, for example SMTP_PASSWORD='a$b'.
After a change, run docker compose up -d. A plain docker compose restart keeps the old environment.
Required values
docker compose refuses to start while this value, or one of the six secrets, is missing.
| Variable | Effect |
|---|---|
PUBLIC_URL | The origin members and agents reach Skilder on. See The public URL. |
The public URL
PUBLIC_URL is a scheme, a host and any port, with no path: https://skilder.example.com. Skilder serves the app at /, the API at /api and the MCP endpoint at /mcp. Every link Skilder emails and every OAuth redirect follows it.
In production mode, the backend refuses to start on a localhost, 127.0.0.1, 0.0.0.0 or [::1] host. The bundled compose.yaml always runs it in production mode, so this applies to every install. To try Skilder on one machine, use a name under .localhost, which browsers and curl send to that machine: http://skilder.localhost, plus the port when SKILDER_HTTP_PORT is not 80.
Skilder serves plain HTTP. Put a reverse proxy that terminates TLS in front of it (Reverse proxy and HTTPS) and set PUBLIC_URL to the https origin. An MCP server that signs in with OAuth needs an https origin: its authorization server refuses the plain-HTTP redirect URI of a .localhost name.
Secrets
You supply six secrets, generated once in the Quick start. No image generates one, and docker compose refuses to start while one is missing. Back up .env with the data directory: restored without its keys, an install cannot read its passwords, sessions and stored secrets.
Generate the secrets
The Quick start runs ./init-env.sh. It generates every secret that is blank or missing in .env, and never rewrites one that is set. Run it again after an upgrade that adds a secret: it fills only the new one.
To manage the keys elsewhere, for example in a secrets manager, generate them with openssl. The values hold only letters, digits, - and _, so none needs quotes:
openssl rand -hex 32 # ENCRYPTION_KEY, SIGNING_KEY, SKILDER_OBJECT_STORE_RPC_SECRET, SKILDER_STORAGE_OBJECT_SECRET_ACCESS_KEY
echo "SYK$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')" # SYSTEM_KEY
echo "GK$(openssl rand -hex 12)" # SKILDER_STORAGE_OBJECT_ACCESS_KEY_IDGenerate the keys once, on a new install. Replacing the keys of an install that has run leaves Skilder unable to read its passwords, sessions and stored secrets.
What each secret does
| Variable | Format | Used for | If you change it |
|---|---|---|---|
ENCRYPTION_KEY | 64 hex characters. At least 32 characters of any kind are accepted. | Verifies passwords, encrypts stored secrets (MCP server configuration secrets, AI provider keys, OAuth client secrets and tokens), and signs sessions. | Passwords stop verifying, sessions are refused, and stored secrets become unreadable. There is no rotation path. |
SYSTEM_KEY | SYK and 43 base64url characters. | Authenticates the runtime and remote-mcp to the backend. | The backend keeps the key it stored on first start, so the runtime and remote-mcp fail their handshake and no tool runs. |
SIGNING_KEY | 64 hex characters. At least 32 characters are accepted, and not the value of ENCRYPTION_KEY. | Signs the short-lived links and delegated sessions the backend issues. They last 15 minutes at most. | The ones issued in the last 15 minutes stop working, and agents request new ones. Recreate the backend with docker compose up -d backend: no other service restarts. |
SKILDER_OBJECT_STORE_RPC_SECRET | 64 hex characters. | The cluster secret of the bundled object store, which holds every workspace file. | The bundled single-node store starts with a new value. Nothing else reads it. |
SKILDER_STORAGE_OBJECT_ACCESS_KEY_ID | GK and 24 hex characters. | The access key id of the bundled object store. The store creates the key when it starts with a new id, and the backend signs in with it. | Change it together with the secret. The store gives the new key the same bucket and keeps the old one. docker compose exec object-store /garage key list shows both; remove the old one with docker compose exec object-store /garage key delete --yes <old id>. |
SKILDER_STORAGE_OBJECT_SECRET_ACCESS_KEY | 64 hex characters. | The secret of that access key. | Alone, the store refuses to start: the id names a key that has another secret. Change the id with it. |
Data, ports and images
| Variable | Default | Effect |
|---|---|---|
IMAGE_TAG | The release you cloned | The Skilder release to run: the tag of the backend, remote-mcp, runtime and frontend images, without the v, for example 0.15.0. init-env.sh writes the cloned release into .env, so checking out a later release does not change it: set it to the release you check out (Upgrade). |
SKILDER_DATA_DIR | data, next to .env | The host directory that holds all state: nats/, dgraph/ and files/, which holds every workspace file. Set an absolute path to put it on another disk: a relative one resolves against the directory of compose.yaml. Docker creates what is missing. Back it up with the stack stopped (Back up and restore). |
SKILDER_HTTP_PORT | 80 | The host port the bundled proxy publishes. It is the stack's only one. Docker publishes it on every interface: prefix an address, for example 127.0.0.1:8080, to listen on that address only. |
SKILDER_SUBNET | 172.20.0.0/16 | The subnet of the Compose network. Pick a range nothing else on the host uses, a second install included. A second install on the host also sets its own COMPOSE_PROJECT_NAME in .env: without it, its docker compose commands act on the first install's containers. Another Docker network in the range makes docker compose up fail with Pool overlaps with other one on this address space. Docker does not check the networks your host routes, such as a LAN or a VPN: one in the range conflicts with the stack's route, and the host's traffic for that range reaches only one of them. Keep it inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16: Dgraph refuses the backend's schema push from any other address, and the backend does not start. The network's gateway is the first address of the range. To change it on an install that has run, also change a SKILDER_TRUSTED_PROXIES that names the old gateway, then run docker compose up -d naming no service: it stops every service, recreates the network and starts them again. Naming a service fails and leaves that service stopped. |
SKILDER_TRUSTED_PROXIES | unset | The reverse proxies in front of the bundled proxy, as addresses or CIDRs separated by commas, for example 10.0.0.5,10.1.0.0/24. The bundled proxy then takes the client address from their X-Forwarded-For. |
SKILDER_BACKEND_IMAGE | backend | The backend image: backend, or backend-ee for the enterprise image, which adds single sign-on. Both read the same data, so switching either way keeps every account, workspace and its history, with no migration: run docker compose pull, then docker compose up -d. |
SKILDER_REGISTRY | ghcr.io/skilder-ai | The registry prefix the four Skilder images are pulled from, for example registry.example.com/skilder. A mirror holds them under the same names and tags, backend-ee too when SKILDER_BACKEND_IMAGE names it, with the whole multi-arch index (linux/amd64 and linux/arm64). NATS, Dgraph, Garage and nginx always come from their publishers. |
Set SKILDER_TRUSTED_PROXIES whenever a reverse proxy or load balancer sits in front (Trust your proxy). Unset, every member shares its address, and so one rate limit, sign-in included. Name only your reverse proxies, never the compose network's subnet, which holds every container of the stack. A reverse proxy on the same machine arrives from the network's gateway (172.20.0.1 by default), which Docker can relay other clients from too: trust it only with the published port closed to everything but your reverse proxy (Before you start).
Sign-in providers
Members sign in with a password, an emailed code or an emailed link. Set both values of a provider to add its button to the sign-in page. A provider missing either value stays off.
Register this redirect URI on the provider's app, with <provider> set to google, github or microsoft: <PUBLIC_URL>/api/auth/callback/<provider>.
| Variables | Provider |
|---|---|
GOOGLE_SIGNIN_CLIENT_ID, GOOGLE_SIGNIN_CLIENT_SECRET | |
GITHUB_SIGNIN_CLIENT_ID, GITHUB_SIGNIN_CLIENT_SECRET | GitHub |
MICROSOFT_SIGNIN_CLIENT_ID, MICROSOFT_SIGNIN_CLIENT_SECRET | Microsoft |
Single sign-on
On the enterprise image (SKILDER_BACKEND_IMAGE=backend-ee), members on your email domains sign in through your identity provider with Continue with SSO. Someone on those domains signing in for the first time gets an account and joins your workspace as a member, as long as the install has one workspace; once it has more, newcomers need an invitation. People with an email on other domains keep their own sign-in. Once SSO is set, only a platform administrator creates workspaces. Set one provider, a generic OIDC one or Microsoft Entra ID, and the domains. The backend applies them at every start: a changed value updates the connection at the next start, and the people who signed in through it keep their accounts. An incomplete set, or both providers, stops the backend at boot with a line naming the variable. The default image ignores them. Single sign-on sets them up, step by step.
| Variable | Effect |
|---|---|
SSO_OIDC_ISSUER | The issuer URL of a generic OIDC provider, exactly as its discovery document names it, https only. Set with SSO_OIDC_CLIENT_ID and SSO_OIDC_CLIENT_SECRET. |
SSO_OIDC_CLIENT_ID | The client id of the app you register at the provider. Its redirect URI is the redirectUri the backend logs at start: docker compose logs backend | grep instance_sso_connection. |
SSO_OIDC_CLIENT_SECRET | That app's client secret. Stored encrypted, never logged. |
SSO_ENTRA_TENANT_ID | Your Microsoft Entra tenant id, a GUID, in place of the three above. Sign-in goes through the Microsoft app of MICROSOFT_SIGNIN_CLIENT_ID and MICROSOFT_SIGNIN_CLIENT_SECRET, which it requires, through your tenant alone, so a single-tenant app registration works. |
SSO_DOMAINS | The email domains that sign in through the provider, separated by commas, for example example.com,example.org. Required with a provider. A domain removed from the list stops offering SSO at the next start. Its people stay bound to your organization: with enforcement on they cannot sign in at all, so turn enforcement off before you remove a domain they still use. |
SSO_ENFORCED | On unless set to false (0, no and off work too). all makes every address sign in only through the provider, whatever its domain: see SSO only; without a provider it stops the backend at boot. Any other value stops the backend at boot. While it is on, people on your domains sign in only through the provider: a password, an emailed code or link, and a social sign-in are refused, and turning it on signs them out of every session that did not come through SSO at the next start. Their API keys keep working. Removing the provider settings leaves enforcement as it was: still on if it was on, until you set SSO_ENFORCED=false. |
SKILDER_BREAK_GLASS | Break-glass access, off by default. While it is set to 1 or true, a platform admin's password is accepted despite SSO_ENFORCED, so you can sign in when the provider fails; everyone else, and every other sign-in method, stays refused. Each use is logged as a warning and recorded. Remove it and restart once SSO works: the restart signs the admin out of the break-glass session and revokes that admin's MCP OAuth tokens. Every restart signs the admin out, so while it stays on, sign in again after each one. A platform admin whose email is off SSO_DOMAINS never needs it. |
Other variables
| Variable | Effect |
|---|---|
PRIVATE_GITHUB_IMPORT_TOKEN | Raises the quota of skill imports from public GitHub repositories from 60 to 5,000 requests per hour. Unset, requests are anonymous. GitHub import token. |
GC_MESSAGE_MAX_ORPHAN_RATIO | The share of all chat messages that may read as orphaned before garbage collection refuses to delete any. Default 0.5. A refused message cleanup. |
SKILDER_CA_BUNDLE | A PEM file of certificate authorities the backend, remote-mcp and main-runtime trust on top of the public ones. Unset, they trust the public ones only. Private certificate authority. |
HTTPS_PROXY, HTTP_PROXY, NO_PROXY | The forward proxy the backend, remote-mcp and main-runtime make their outbound HTTP calls through, and the hosts they reach directly. Unset, every call goes out directly. Outbound proxy. |
SKILDER_ONBOARDING_V2_ENABLED | Turns on the new onboarding flow for new accounts, still in preview: on or off, also true/false, yes/no or 1/0. Unset, it is off. Any other value stops the backend at boot. |
POSTHOG_KEY | The project key for the web analytics, session replay and error reports the app records in members' browsers. The frontend container forwards them to PostHog's EU servers (Outbound access). Unset, the app records none. |
The backend emails sign-in codes, sign-in links, invitations, password resets, email verification links and new sign-in method alerts. EMAIL_PROVIDER decides whether they are sent:
| Value | Effect |
|---|---|
log | Default. The backend logs each email and never sends it. |
smtp | The backend sends each email through your mail server. |
Any other value stops the backend at boot.
Without a mail server
With log, the backend warns at boot (email_delivery_disabled) that no email is sent. It writes every sign-in code, sign-in link, invitation link, password reset link and email verification link to its log instead:
docker compose logs backend | grep -E 'Sign-in code|Sign-in link|Invitation URL|Password reset URL|Email verification URL'A member who set a password still signs in with it, and Google, GitHub or Microsoft sign-in works where you configured it. Anyone who can read the backend log can sign in as any member: they request a code for that address and read it from the log. Set up smtp before you invite anyone.
Send through your mail server
Set these in .env:
| Variable | Required | Default | Effect |
|---|---|---|---|
EMAIL_PROVIDER | yes | log | Set to smtp. |
SMTP_HOST | yes | Mail server host. | |
SMTP_TLS | no | starttls | tls: TLS from the first byte. starttls: upgrades a plain connection, and refuses a server that cannot. none: never upgrades, for a local relay only. |
SMTP_PORT | no | 465 with tls, 587 otherwise | Mail server port, 1 to 65535. |
SMTP_USER, SMTP_PASSWORD | no | Set both, or neither for a server that needs no authentication. Single-quote a password holding $ or #. | |
EMAIL_FROM | yes | Sender address, on a domain your mail server may send for. | |
EMAIL_FROM_NAME | no | Skilder | Sender display name in the From header. |
EMAIL_SIGNATURE | no | Skilder | Name the plain-text version of an email signs off with, in the emails that sign off. Set apart from EMAIL_FROM_NAME: neither changes the other. |
EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_TLS=starttls
SMTP_USER=skilder
SMTP_PASSWORD='...'
EMAIL_FROM=skilder@example.com
EMAIL_FROM_NAME=Acme SkilderA missing host, a port outside 1 to 65535, an unknown SMTP_TLS value, only one of SMTP_USER and SMTP_PASSWORD, or a missing EMAIL_FROM stops the backend at boot, with a message naming the variable. Recreate the backend with docker compose up -d backend after any change.
Sender identity
Every email carries a logo, a reply-to inbox and a footer. The defaults name Skilder, so replies go to Skilder unless you change them:
| Variable | Default | Effect |
|---|---|---|
EMAIL_REPLY_TO | hello@skilder.ai | Reply-to inbox, also shown in the footer. |
EMAIL_FOOTER_TEXT | © Skilder, Lausanne - Switzerland | Sender name and location in the footer. |
EMAIL_LOGO_URL | <PUBLIC_URL>/logo-skilder-email.png | Logo at the top of every email. |
Check email works
Request a sign-in code for your own address on the sign-in page. The backend logs email_sent with provider set to smtp once your mail server accepts it. The sign-in page answers the same whether or not the send succeeds, so read the log, not the page.
A failed send logs email_send_failed with an errorName, plus the server's statusCode when it answered. It never logs the recipient or the server's reply.
The warning banner
While email does not work, a banner tells workspace admins at the top of the app: No email provider is configured, or The mail server cannot be reached. Members never see it, and it cannot be dismissed.
With smtp, the backend connects to your mail server at boot and every 5 minutes, signs in with SMTP_USER and SMTP_PASSWORD when they are set and the server offers sign-in, as a send does, and disconnects. It sends no email, so a server that accepts the connection but refuses the message itself does not show the banner: one that needs credentials you have not set, or one that offers sign-in only over TLS while SMTP_TLS is none. The banner clears by itself a few minutes after the server recovers, with no restart, and appears if a working server later fails. Each change logs email_status_changed. A failure adds an errorName, plus the server's statusCode when it answered, and never the host, the account or the server's reply.
GitHub import token
Importing a skill from GitHub reads the repository from api.github.com and raw.githubusercontent.com. Without a token, the backend makes these requests anonymously, and GitHub allows 60 per hour. One import costs several requests, so a few imports use up the hour.
Set PRIVATE_GITHUB_IMPORT_TOKEN and the backend sends it on every request to those two hosts. The limit becomes 5,000 requests per hour, shared by every workspace on the install. Members never enter a GitHub credential.
The token reads public repositories only. Importing from a private repository is not supported.
Create the token
Use a service account
Sign in to GitHub as a service account owned by your organization, not as a person.
Generate a fine-grained token
Go to Settings > Developer settings > Personal access tokens > Fine-grained tokens and click Generate new token.
Restrict it to public content
Set Resource owner to the service account and Repository access to Public repositories (read-only). Grant no permissions: reading public content needs none.
Set the expiration
Choose the longest expiration your organization allows, and record the expiry date where your team tracks renewals.
Copy the token
GitHub shows the token (github_pat_...) once. Copy it into your secret store.
Set the token
Add the variable to the backend environment from your secret store. Never commit the value. With the bundled compose.yaml, put it in .env:
PRIVATE_GITHUB_IMPORT_TOKEN=github_pat_...Then recreate the backend with docker compose up -d backend. A plain docker compose restart keeps the old environment. Leave the variable unset or empty to keep anonymous requests.
Check it worked
With TOKEN holding the token in your shell:
curl -s -H "Authorization: Bearer $TOKEN" https://api.github.com/rate_limitThe core limit in the response is 5000. Without the header, it is 60.
Rotate the token
- Create a new token with the same settings.
- Replace the secret and recreate the backend with
docker compose up -d backend, as in Set the token. - Revoke the old token in GitHub.
When the quota runs out, an import fails with a message giving the time GitHub resets it, when GitHub sends one. When GitHub rejects the token (expired or revoked), every import fails until you replace it. The backend does not fall back to anonymous requests.

