How to configure thread/checkpointer TTL when deploying the LangGraph Server with Docker using environment variables?

OSS Product Help LangGraph
,
1

Hi everyone,

I’m deploying a LangGraph Server using Docker.

Instead of providing a langgraph.json file, my deployment config is generated entirely from environment variables (similar to how variables like LANGSERVE_GRAPHS can be configured).

I’m trying to configure the thread/checkpointer TTL described in the documentation:

The documentation explains how to configure TTL in langgraph.json, for example under checkpointer.ttl, but I couldn’t find the equivalent environment variables that the server recognizes.

My questions are:

  • Is there an environment variable equivalent for the checkpointer.ttl (and/or store.ttl) configuration?

  • If so, what are the expected variable names and format?

My goal is to deploy the server without shipping a langgraph.json file and configure everything through environment variables.

Thanks!

2

Hi @gdrouet!

Yes, there’s a LANGGRAPH_THREAD_TTL environment variable. It takes either a number of minutes or a full JSON object:

# Shorthand, in minutes. Implies strategy=delete, sweep_interval_minutes=5.1, sweep_limit=10000
LANGGRAPH_THREAD_TTL=43200

# Full control
LANGGRAPH_THREAD_TTL='{"strategy":"delete","default_ttl":43200,"sweep_interval_minutes":10,"sweep_limit":10000}'

For store.ttl there’s no shorthand. Pass the whole store block:

LANGGRAPH_STORE='{"ttl":{"refresh_on_read":true,"default_ttl":10080,"sweep_interval_minutes":120}}'

Both are read at startup, so they need to be set before the container boots.

This is a gap in our docs. Thanks for flagging it.

3

Thank you. Please note that only JSON is accepted:

Error loading config from : failed to apply env “LANGGRAPH_THREAD_TTL” to field ThreadTTL: invalid JSON value “10”: json: cannot unmarshal number into Go value of type config.ThreadTTLConfig

4

@gdrouet can you try the full JSON form? A bare number isn’t accepted; LANGGRAPH_THREAD_TTL expects a JSON object:

LANGGRAPH_THREAD_TTL='{"strategy":"delete","default_ttl":10,"sweep_interval_minutes":5,"sweep_limit":10000}'

Note that default_ttl is in minutes (so 10 = 10 minutes; use 43200 for 30 days). Set this before the container starts / restart the server so it picks it up.

5

Yes it works!

This TTL means that thread is deleted only if no message are sent in the time windows right?

Thanks

6

@gdrouet if it helped you can you mark the answer as solution.

7

@keenborder786 Yes but can you answer to my last question please?

8

@gdrouet No, with "strategy": "delete", the TTL does not reset on new messages. The timer starts when the TTL is applied and the thread is deleted after default_ttl minutes, even if there is activity.

If you want the window to refresh on activity (run finishes / thread state updates), use "strategy": "keep_latest" instead.
Doc Reference: How to add TTLs to your application - Docs by LangChain

9

Thanks for clarification.