Optional services

This page is for operators of a self-hosted instance. It lists the services an instance runs without, what each needs, how to turn it on, and how to turn it off again. Installing the instance itself is Self-hosting.

Every setting below is a value of a chart, and every key is a Secret that deploy/k8s/bootstrap-secrets.sh writes. The tables are read from the charts' values.yaml when this page is built, so their defaults are the committed ones: they are instruction.md's own, and the addresses in them are yours to replace.

At a glance

Service On when Off
Outgoing mail config.mail.enabled and IMD_SMTP_PASSWORD in the Secret imd-svc Either one missing. Requests are still stored
Billing with Stripe IMD_STRIPE_SECRET_KEY (and IMD_STRIPE_WEBHOOK_SECRET) in the Secret imd-svc No key. Nobody can pay, and the billing tools say so
The assistant config.assistant.enabled and IMD_OPENAI_API_KEY in the Secret imd-svc Either one missing. The editor shows no assistant
The egress proxy egressProxy.https on the gateway Empty: the gateway connects directly
Contracted plans An entry in deploy/k8s/plans.json, applied by apply-plans.mjs No entry. Organizations are on the plan they chose
The sealed key service instruction-mcp --http running with an organization's key-service key Not running. Sealed instructions stay sealed for AI apps
Sign-in brokers brokers in the realm profile, and KC_BROKER_<NAME>_CLIENT_ID and _SECRET in imd-keycloak-clients No brokers: the brokers are off and nobody can sign up. No secrets: the apply job skips that broker

A key that bootstrap-secrets.sh finds in the Secret is kept on every later run, whether or not the environment has it. So to turn a service off, take its key out of the Secret, then roll imd-svc:

Shell
# turn a service off: take its key out of the Secret, then roll imd-svc
kubectl -n instruction-md patch secret imd-svc --type=json -p='[{"op":"remove","path":"/data/IMD_OPENAI_API_KEY"}]'
kubectl -n instruction-md rollout restart deploy/imd-svc

On an upgrade, pass a hash of the Secret as secretRevision and the pods roll even on the same image: the chart puts it on them. The Stripe steps below show it.

Outgoing mail

A stored support or contact request mails the person a confirmation with their request number, and the staff mailbox a notice. Nothing is queued or sent unless config.mail.enabled is true and the Secret imd-svc holds IMD_SMTP_PASSWORD. Keycloak's own mail (address verification) is set in the realm profile's smtp, apart from this.

ValueDefaultVariableEffect
config.mail.enabledtrueIMD_MAILMail is queued and sent only when this is true and the Secret imd-svc holds IMD_SMTP_PASSWORD. Either alone sends nothing.
config.mail.fromnoreply@instruction.mdIMD_MAIL_FROMThe sender's address, plain and lower case.
config.mail.fromNameinstruction.mdIMD_MAIL_FROM_NAMEThe sender's name: letters, digits, spaces and . _ - only, up to 60 characters.
config.mail.supportsupport@instruction.mdIMD_MAIL_SUPPORTThe staff mailbox that gets a notice of each request.
config.mail.smtpHostmail.tsok.orgIMD_SMTP_HOSTThe relay's host name. Its certificate is checked against this name.
config.mail.smtpPort465IMD_SMTP_PORTThe relay's port. imd-svc speaks implicit TLS (SMTPS), not STARTTLS.
config.mail.smtpUser""IMD_SMTP_USERThe user to sign in to the relay as. Empty: the sender's address.

To turn it on, set the values and give imd-svc the relay's password:

Values
# <svc-values.yaml>
config:
  mail:
    enabled: true
    from: noreply@<your domain>
    fromName: instruction.md
    support: support@<your domain>
    smtpHost: <relay host>
    smtpPort: 465
    smtpUser: ""        # empty: the sender's address
Shell
# the relay password, into the Secret imd-svc; bootstrap-secrets.sh keeps it on every later run
IMD_SMTP_PASSWORD=<relay password> deploy/k8s/bootstrap-secrets.sh instruction-md
kubectl -n instruction-md rollout restart deploy/imd-svc

Each pod's log then says:

Log
mail: on, as noreply@<your domain> through <relay host>:465

When something is missing, the log names it, never a value:

Log
IMD_MAIL is on but IMD_SMTP_PASSWORD is not set: no mail is queued or sent

imd-svc connects with implicit TLS (secure: true) and checks the relay's certificate against smtpHost. Your relay should sign the sender's domain with DKIM and be covered by its SPF record. Send one request from /support/ with an address you read: the confirmation should arrive within a minute.

A mail is sent at least once: a pod stopped between the relay's answer and the row's update sends it again ten minutes later, with the same Message-ID. A confirmation addressed to the service's own sender (config.mail.from) or to the staff mailbox is never sent: the row ends as failed with refused:address.

Off. Set config.mail.enabled: false and upgrade imd-svc. New requests queue nothing, and rows already queued are given up a day after they were written. To stop at once without a deploy, hold what is waiting:

SQL
-- hold what is waiting, without a deploy
UPDATE imd.mail_outbox SET state = 'failed', error = 'held', updated_at = now() WHERE state = 'queued';

Billing with Stripe

Billing lets organizations buy Pro and Team through Stripe's checkout and manage them in Stripe's customer portal. Without Stripe's keys, nobody can pay, and every organization stays on the plan it has. The plans, their limits and prices are billing/plans.json: the migration loads it, and billing/stripe-setup.mjs makes Stripe's products and prices from it. Change a figure there, not in Stripe.

A payment becomes a plan only one way: Stripe calls POST /billing/webhook, signed, and imd-svc reads the organization's subscriptions back from Stripe. Nothing in a request or a webhook's body is trusted for it. The worker also re-reads every paying organization every 30 minutes.

What you need:

  • A Stripe account. Test mode is enough to start.
  • Its secret key (sk_test_…), for the setup script only. The script never prints or stores it.
  • A restricted key for the server, with only Customers write, Checkout Sessions write, Customer portal write, Subscriptions write, Prices read and Products read.
Shell
# 1. the products, prices, customer portal and webhook endpoint, made from billing/plans.json
STRIPE_SECRET_KEY=sk_test_… node billing/stripe-setup.mjs --check
STRIPE_SECRET_KEY=sk_test_… node billing/stripe-setup.mjs --webhook-url https://<your host>/billing/webhook
#    the endpoint's signing secret is written to stripe-webhook-secret.test.txt (mode 0600)

# 2. the server's restricted key and the signing secret, into the Secret imd-svc
IMD_STRIPE_SECRET_KEY=rk_test_… IMD_STRIPE_WEBHOOK_SECRET="$(cat stripe-webhook-secret.test.txt)" \
  deploy/k8s/bootstrap-secrets.sh instruction-md
shred -u stripe-webhook-secret.test.txt

# 3. roll imd-svc: a changed Secret rolls the pods through secretRevision
helm upgrade imd-svc deploy/k8s/imd-svc -n instruction-md --reuse-values \
  --set secretRevision="$(kubectl -n instruction-md get secret imd-svc -o jsonpath='{.data}' | sha256sum | cut -c1-16)" --wait

--check changes nothing: it lists what it would make (differs …) and exits 1 on a fresh account. Run the setup again and it answers as it is for everything, exit 0. The webhook route is the imd-svc chart's (route.webhook): exactly that path, POST only, with no authentication at the edge, because imd-svc checks Stripe's signature over the exact bytes. To check it:

Shell
curl -s -X POST https://<your host>/billing/webhook
# {"error":{"code":"validation","message":"not a delivery from Stripe: …"}}   the route and the secret are in place
# 404                                                                         the webhook secret isn't loaded
# the site's 404 page                                                         the chart's webhook route is missing

Then build the site with PUBLIC_IMD_BILLING=on, so the plans page states its prices as charged. Live mode is the same steps with live keys: it has its own products, prices, portal and webhook endpoint, so the script makes them again and writes a new signing secret.

Off. Remove IMD_STRIPE_SECRET_KEY and IMD_STRIPE_WEBHOOK_SECRET from the Secret imd-svc (as above) and from your secret store, then roll imd-svc. Nobody can start paying. Existing subscriptions keep their plans to the end of their period and a grace of 7 days (graceDays in billing/plans.json), then the organizations are on Community.

The assistant

The editor's assistant writes and edits with people, on OpenAI's API. Each step goes to apiBase, which by default is OpenAI's own API, hosted in the US. It is on only when config.assistant.enabled is true and the Secret imd-svc holds IMD_OPENAI_API_KEY. Without either, /api/assistant answers 404 and the editor shows no assistant. An organization can also turn it off for its own people.

ValueDefaultVariableEffect
config.assistant.enabledtrueIMD_ASSISTANTThe assistant is on only when this is true and the Secret imd-svc holds IMD_OPENAI_API_KEY.
config.assistant.apiBasehttps://api.openai.com/v1IMD_OPENAI_API_BASEThe base URL of OpenAI's API that every step is sent to.
config.assistant.modelgpt-6.1-terraIMD_ASSISTANT_MODELThe chat model.
config.assistant.dailyCredits20000IMD_ASSISTANT_DAILY_CREDITSWhat every account together may spend in a UTC day, in credits (a credit is a thousandth of a US dollar). Past it the assistant rests until the next day.
config.assistant.perPersonPerMinute20IMD_ASSISTANT_PER_PERSON_PER_MINUTESteps a minute for one person.
config.assistant.perMinute120IMD_ASSISTANT_PER_MINUTESteps a minute for everyone together.
config.assistant.perAddressDaily5000IMD_ASSISTANT_PER_ADDRESS_DAILYCredits of free allowances one client address may use in a day, whoever is signed in there. Paid workspaces are not held to it.
config.assistant.context[]IMD_ASSISTANT_CONTEXTMCP servers the assistant may look things up in: label, url, about, tools, tokenEnv (the Secret's key that holds the bearer token), identity. Empty: none.
config.assistant.voice(below)Talking to the assistant (below).
config.assistant.voice.enabledtrueIMD_ASSISTANT_VOICESpoken conversations. Off: /api/assistant/call answers 404 and the editor shows no way to talk.
config.assistant.voice.modelgpt-live-1IMD_ASSISTANT_VOICE_MODELThe voice model.
config.assistant.voice.namemarinIMD_ASSISTANT_VOICE_NAMEThe voice.
config.assistant.voice.maxCalls10IMD_ASSISTANT_MAX_CALLSCalls open at once over the whole service.
Values and the key
# <svc-values.yaml>
config:
  assistant:
    enabled: true
    voice: { enabled: false }

# the key, into the Secret imd-svc
IMD_OPENAI_API_KEY=<your OpenAI key> deploy/k8s/bootstrap-secrets.sh instruction-md

The pods' outbound traffic must reach apiBase, and each context source's url. Keep each source's token in the Secret under the name its tokenEnv gives, never in values.

Off. Set config.assistant.enabled: false and upgrade imd-svc, or take IMD_OPENAI_API_KEY out of the Secret. Set config.assistant.voice.enabled: false to keep typing and turn off talking.

Search by meaning

The embedding model (imd-embeddings) runs Text Embeddings Inference with BAAI/bge-base-en-v1.5 (768 dimensions) inside the cluster. imd-svc's worker embeds each released version's sections at http://imd-embeddings:80/v1/embeddings, and the gateway embeds each instructions_search query there. No instruction text leaves the cluster to be embedded.

It is part of the generated gateway config, so it isn't optional as configured: without it, instructions_search fails at its embed step. Listing by words (instructions_list with query) doesn't use it. Its first start fetches the weights from huggingface.co. On a cluster with no way there, load the weights into the model's volume and set model.path, and nothing is fetched.

The egress proxy

The gateway pulls its first-party plugins from ghcr.io at every start. Where the cluster reaches the internet only through a proxy, give the gateway one:

ValueDefaultEffect
egressProxy.https""An HTTP CONNECT proxy for the gateway's outbound HTTPS (its plugins from ghcr.io at start). Empty: direct.
egressProxy.noProxylocalhost,127.0.0.1,.svc,.cluster.local,imd-svc,imd-embeddings,imd-keycloak,imd-nats,imd-pgbouncer,imd-postgres-rwAddresses that never go through the proxy: the cluster's own services.
Values
# <gateway-values.yaml>
egressProxy:
  https: http://<proxy host>:3128

The local stack does this on its own when its pods can't reach ghcr.io: it applies deploy/k8s/stack/egress-proxy.yaml, a CONNECT-only proxy on the node's network that allows port 443 alone, and points the gateway at http://imd-egress:3128. It isn't meant for a production cluster: use your own proxy there.

What reaches outside, and only when you turn it on:

From To When
The gateway ghcr.io (its plugins) every start
The embedding model huggingface.co its first start, unless the weights are loaded
imd-svc your mail relay mail is on
imd-svc api.stripe.com Stripe's key is set
imd-svc apiBase and the context sources the assistant is on
Keycloak the brokers' and organizations' identity providers a broker or an organization's sign-in is set up

Outbound rules for the pods are your cluster's to set. Keycloak's chart has its own (egressPolicy, off by default), which allows DNS, the database, the other replicas and public addresses.

Contracted plans

Organizations normally choose their plan and pay for it through Stripe. An organization on a contract (yours, for example, on a self-hosted instance) gets its plan from deploy/k8s/plans.json instead. Its source is contract, so Stripe never changes it, and the organization isn't offered checkout.

deploy/k8s/plans.json
{
  "orgs": {
    "acme": { "plan": "enterprise", "source": "contract", "why": "our own organization" }
  }
}

A plan is one of: community (Community), pro (Pro), team (Team), enterprise (Enterprise). deploy/k8s/apply-plans.mjs sets each entry through the MCP server as the platform's own service (platform-automation), so the gateway authorizes and audits it like any call:

Shell
PLATFORM_AUTOMATION_SECRET=$(kubectl -n instruction-md get secret imd-keycloak-clients \
    -o 'jsonpath={.data.KC_PLATFORM_AUTOMATION_SECRET}' | base64 -d) \
  IMD_MCP_URL=https://<your host>/mcp IMD_ISSUER=https://<your host>/auth/realms/instruction-md \
  node deploy/k8s/apply-plans.mjs [plans.json]

It writes only what differs. An organization that doesn't exist yet is reported and left for the next run. Matched by its slug alone, an entry would go to whoever made that slug first, so once the organization exists, pin it with orgId: the script prints the id to pin.

Off. Remove the entry. The plan stays as it was set until it is changed; set the entry to community first to take a contract away.

The sealed key service

Plans On Team and Enterprise

Sealed workspaces are in beta, not yet independently reviewed. Their instructions are encrypted before they reach the server, so an AI app that only speaks to /mcp gets them still sealed. The company proxy opens them: instruction-mcp --http is an MCP endpoint of your own that people's AI apps sign in to as they do to your instance. It sends each request on with that person's token, and opens what they may read with the organization's key-service key. Point it at your instance with --url; its sign-in issuer then defaults to /auth/realms/instruction-md on the same host.

Shell
# an organization's key-service key (an admin of the organization, signed in to your instance)
instruction login --url https://<your host>/mcp
instruction-mcp key init --key-service --org acme --file ks.key

# the company proxy, in front of your instance
instruction-mcp --http 8780 --public-url https://mcp.acme.example --key-file ks.key \
  --url https://<your host>/mcp --allow-domain acme.example

The same as a container:

Shell
docker run -p 8780:8780 -v /secure/ks.key:/keys/ks.key:ro \
  -e INSTRUCTION_MD_PUBLIC_URL=https://mcp.acme.example -e INSTRUCTION_MD_SEAL_KEY_FILE=/keys/ks.key \
  -e INSTRUCTION_MD_URL=https://<your host>/mcp -e INSTRUCTION_MD_ALLOW_DOMAINS=acme.example \
  ghcr.io/instruction-md/mcp:<version>

TLS is yours, in front of it. Keep the key in your KMS or secret store and hand it over with --key-command, which runs a command at start and reads the key it prints. Then give each sealed workspace's key to the key service in the editor, or with seal_wraps_add. Every flag is in instruction-mcp, and how sealing works is in Sealed instructions for developers.

Off. Stop the proxy. AI apps that reach your instance directly get sealed instructions still sealed; people who hold their own key can still open them in the editor or with instruction-mcp on their machine.

Sign-in brokers

People can sign in with GitHub, Google or Microsoft through Keycloak. Every committed realm profile has the three brokers off. To turn them on:

  1. Set "brokers": True in your profile in deploy/keycloak/gen-realms.py, and regenerate the realms. The three brokers are then enabled, and Keycloak's sign-up page is on: without brokers (or the stack's dev_users), nobody can sign up.
  2. Register an OAuth app with each provider, and give bootstrap-secrets.sh its id and secret: KC_BROKER_GITHUB_CLIENT_ID and KC_BROKER_GITHUB_SECRET, and the same for GOOGLE and MICROSOFT. A broker whose secrets aren't in imd-keycloak-clients is skipped by the apply job, which logs SKIP identityProviders/<alias>: needs KC_….
  3. Upgrade Keycloak. An organization's own identity provider is an sso entry in your realm profile in deploy/keycloak/gen-realms.py, with its client in KC_BROKER_<ALIAS>_CLIENT_ID and KC_BROKER_<ALIAS>_SECRET. bootstrap-secrets.sh passes on only the broker names in its list, so add the two names there as well.

After a broker's secret changes, upgrade Keycloak with apply.overwrite=true so the apply job recreates the changed client.

Last checked against the product:

Was this page helpful? Report a problem