Resolved runtime configuration for planck_headless.
Config is resolved by Skogsra, which reads from three sources in priority order (highest first):
- Environment variables (
PLANCK_*) - Application config —
config :planck, <key>, ... - Hardcoded defaults
Values are cached in persistent terms via preload/0 at application boot;
the application also calls validate!/0 to fail fast on malformed config.
To change a value at runtime, set the application env and call the
Skogsra-generated reload_<key>/0 function.
JSON config files (~/.planck/config.json and .planck/config.json) are
read via JsonBinding (internal module) as part of Skogsra's binding chain. Keys that appear
in a JSON file override application config but are overridden by env vars.
Env vars
Planner config
| Env var | Config key | Default |
|---|---|---|
PLANCK_DEFAULT_PROVIDER | :default_provider | nil |
PLANCK_DEFAULT_MODEL | :default_model | nil |
PLANCK_SESSIONS_DIR | :sessions_dir | .planck/sessions |
PLANCK_SKILLS_DIRS | :skills_dirs | .planck/skills:~/.planck/skills |
PLANCK_TEAMS_DIRS | :teams_dirs | .planck/teams:~/.planck/teams |
PLANCK_SIDECAR | :sidecar | .planck/sidecar |
*_DIRS env vars take a colon-separated list; paths are expanded at runtime
(~ and relative paths resolved). The :models key has no env var
equivalent — declare models in .planck/config.json or
config :planck, :models, [...].
Provider API keys
API keys are not included in get/0 or the %Config{} struct to avoid
accidental exposure in logs or inspect output. Use the generated getter
functions directly (e.g. Planck.Headless.Config.anthropic_api_key!/0).
| Env var | Config key | Used for |
|---|---|---|
ANTHROPIC_API_KEY | :anthropic_api_key | Anthropic (Claude) models |
OPENAI_API_KEY | :openai_api_key | OpenAI models |
GOOGLE_API_KEY | :google_api_key | Google (Gemini) models |
Summary
Functions
Anthropic API key.
Anthropic API key.
Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).
Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).
Default model id within the default provider (e.g. claude-sonnet-4-6).
Default model id within the default provider (e.g. claude-sonnet-4-6).
Default provider key — references an entry in the providers map (e.g. "anthropic").
Default provider key — references an entry in the providers map (e.g. "anthropic").
Ordered list of .env files to read for API keys.
Global file is read first; project-local file wins on collision.
Not read from the .env files themselves — that would be circular.
Ordered list of .env files to read for API keys.
Global file is read first; project-local file wins on collision.
Not read from the .env files themselves — that would be circular.
Return the fully-resolved config as a %Planck.Headless.Config{} struct.
Google API key.
Google API key.
UI locale (e.g. "en", "es"). Set in .planck/config.json for a
project-specific language or in ~/.planck/config.json for a global
preference. When absent the browser's Accept-Language header is used,
falling back to English.
UI locale (e.g. "en", "es"). Set in .planck/config.json for a
project-specific language or in ~/.planck/config.json for a global
preference. When absent the browser's Accept-Language header is used,
falling back to English.
List of model declarations. Each entry references a key in providers and
assigns a user alias. Only readable from .planck/config.json or application
config — no env var equivalent (the format is too structured for a flat string).
List of model declarations. Each entry references a key in providers and
assigns a user alias. Only readable from .planck/config.json or application
config — no env var equivalent (the format is too structured for a flat string).
OpenAI API key.
OpenAI API key.
Preloads all variables in a namespace if supplied.
Map of named provider entries. Each key is a user-defined provider alias;
the value describes the provider type and connection details. Only readable
from .planck/config.json or application config — no env var equivalent.
Map of named provider entries. Each key is a user-defined provider alias;
the value describes the provider type and connection details. Only readable
from .planck/config.json or application config — no env var equivalent.
Puts the value to Planck.Headless.Config.anthropic_api_key/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.config_files/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.default_model/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.default_provider/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.env_files/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.google_api_key/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.locale/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.models/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.openai_api_key/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.providers/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.secrets_hook/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.sessions_dir/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.sidecar/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.skills_dirs/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.teams_dirs/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.tool_proxy/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.tool_proxy_ca_cert/0. Optionally, receives
the namespace.
Puts the value to Planck.Headless.Config.top_skills/0. Optionally, receives
the namespace.
Reloads the value for Planck.Headless.Config.anthropic_api_key/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.config_files/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.default_model/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.default_provider/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.env_files/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.google_api_key/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.locale/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.models/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.openai_api_key/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.providers/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.secrets_hook/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.sessions_dir/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.sidecar/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.skills_dirs/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.teams_dirs/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.tool_proxy/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.tool_proxy_ca_cert/0. Optionally, receives
the namespace for the variable.
Reloads the value for Planck.Headless.Config.top_skills/0. Optionally, receives
the namespace for the variable.
Module that implements Planck.Headless.Secrets for storing and retrieving
API keys. Defaults to Planck.Headless.Secrets.EnvFile (reads/writes
.planck/.env). Set to "Sidecar.Secrets.AgentVault" to store credentials
in agent-vault instead.
Module that implements Planck.Headless.Secrets for storing and retrieving
API keys. Defaults to Planck.Headless.Secrets.EnvFile (reads/writes
.planck/.env). Set to "Sidecar.Secrets.AgentVault" to store credentials
in agent-vault instead.
Path to the sessions directory.
Path to the sessions directory.
Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.
Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.
Colon-separated list of skill directories.
Colon-separated list of skill directories.
Colon-separated list of team directories.
Colon-separated list of team directories.
Creates a template for OS environment variables given a filename.
Additionally, it can receive a list of options
HTTP proxy URL for all outgoing LLM requests (e.g. "http://vault:14322").
When set, Planck configures its HTTP client to route LLM API calls through
this proxy and sets standard proxy env vars for child processes (bash tools,
sidecar, etc.). Designed for use with credential-injecting proxies such as
agent-vault.
HTTP proxy URL for all outgoing LLM requests (e.g. "http://vault:14322").
When set, Planck configures its HTTP client to route LLM API calls through
this proxy and sets standard proxy env vars for child processes (bash tools,
sidecar, etc.). Designed for use with credential-injecting proxies such as
agent-vault.
Path to the proxy CA certificate PEM file (e.g. "/certs/ca.pem").
Required when using a TLS MITM proxy such as agent-vault. Planck passes
this to its HTTP client and sets SSL_CERT_FILE/CURL_CA_BUNDLE for
child processes.
Path to the proxy CA certificate PEM file (e.g. "/certs/ca.pem").
Required when using a TLS MITM proxy such as agent-vault. Planck passes
this to its HTTP client and sets SSL_CERT_FILE/CURL_CA_BUNDLE for
child processes.
Maximum number of recently-used skills shown in the agent skill index.
Maximum number of recently-used skills shown in the agent skill index.
Validates that all required variables are present.
Returns :ok if they are, {:error, errors} if they are not. errors
will be a list of all errors encountered while getting required variables.
Validates that all required variables are present.
Returns :ok if they are, raises if they're not.
Types
@type t() :: %Planck.Headless.Config{ default_model: String.t() | nil, default_provider: String.t() | nil, models: [map()], providers: %{required(String.t()) => map()}, secrets_hook: String.t() | nil, sessions_dir: Path.t(), sidecar: Path.t(), skills_dirs: [Path.t()], teams_dirs: [Path.t()], tool_proxy: String.t() | nil, tool_proxy_ca_cert: String.t() | nil }
The resolved configuration struct returned by get/0.
Functions
@spec anthropic_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Anthropic API key.
Calling Planck.Headless.Config.anthropic_api_key() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "ANTHROPIC_API_KEY"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec anthropic_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Anthropic API key.
Bang version of Planck.Headless.Config.anthropic_api_key/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec config_files(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).
Calling Planck.Headless.Config.config_files() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_CONFIG_FILES"
- Type: Planck.Headless.Config.PathList
- Default: ["~/.planck/config.json", ".planck/config.json"]
- Required: false
- Cached: true
@spec config_files!(Skogsra.Env.namespace()) :: Planck.Headless.Config.PathList.t() | no_return()
Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).
Bang version of Planck.Headless.Config.config_files/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec default_model(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Default model id within the default provider (e.g. claude-sonnet-4-6).
Calling Planck.Headless.Config.default_model() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_DEFAULT_MODEL"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec default_model!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Default model id within the default provider (e.g. claude-sonnet-4-6).
Bang version of Planck.Headless.Config.default_model/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec default_provider(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Default provider key — references an entry in the providers map (e.g. "anthropic").
Calling Planck.Headless.Config.default_provider() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_DEFAULT_PROVIDER"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec default_provider!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Default provider key — references an entry in the providers map (e.g. "anthropic").
Bang version of Planck.Headless.Config.default_provider/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec env_files(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Ordered list of .env files to read for API keys.
Global file is read first; project-local file wins on collision.
Not read from the .env files themselves — that would be circular.
Calling Planck.Headless.Config.env_files() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_ENV_FILES"
- Type: Planck.Headless.Config.PathList
- Default: ["~/.planck/.env", "./.planck/.env"]
- Required: false
- Cached: true
@spec env_files!(Skogsra.Env.namespace()) :: Planck.Headless.Config.PathList.t() | no_return()
Ordered list of .env files to read for API keys.
Global file is read first; project-local file wins on collision.
Not read from the .env files themselves — that would be circular.
Bang version of Planck.Headless.Config.env_files/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec get() :: t()
Return the fully-resolved config as a %Planck.Headless.Config{} struct.
@spec google_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Google API key.
Calling Planck.Headless.Config.google_api_key() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "GOOGLE_API_KEY"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec google_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Google API key.
Bang version of Planck.Headless.Config.google_api_key/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec locale(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
UI locale (e.g. "en", "es"). Set in .planck/config.json for a
project-specific language or in ~/.planck/config.json for a global
preference. When absent the browser's Accept-Language header is used,
falling back to English.
Calling Planck.Headless.Config.locale() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_LOCALE"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec locale!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
UI locale (e.g. "en", "es"). Set in .planck/config.json for a
project-specific language or in ~/.planck/config.json for a global
preference. When absent the browser's Accept-Language header is used,
falling back to English.
Bang version of Planck.Headless.Config.locale/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec models(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.Models.t()} | {:error, binary()}
List of model declarations. Each entry references a key in providers and
assigns a user alias. Only readable from .planck/config.json or application
config — no env var equivalent (the format is too structured for a flat string).
Example (in .planck/config.json):
"models": [
{ "id": "sonnet", "model": "claude-sonnet-4-6", "provider": "anthropic" },
{ "id": "llama70b", "model": "meta/llama-3.3-70b-instruct", "provider": "nvidia",
"params": { "temperature": 0.6, "receive_timeout": 600000 } }
]Calling Planck.Headless.Config.models() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_MODELS"
- Type: Planck.Headless.Config.Models
- Default: []
- Required: false
- Cached: true
@spec models!(Skogsra.Env.namespace()) :: Planck.Headless.Config.Models.t() | no_return()
List of model declarations. Each entry references a key in providers and
assigns a user alias. Only readable from .planck/config.json or application
config — no env var equivalent (the format is too structured for a flat string).
Example (in .planck/config.json):
"models": [
{ "id": "sonnet", "model": "claude-sonnet-4-6", "provider": "anthropic" },
{ "id": "llama70b", "model": "meta/llama-3.3-70b-instruct", "provider": "nvidia",
"params": { "temperature": 0.6, "receive_timeout": 600000 } }
]Bang version of Planck.Headless.Config.models/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec openai_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
OpenAI API key.
Calling Planck.Headless.Config.openai_api_key() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "OPENAI_API_KEY"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec openai_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
OpenAI API key.
Bang version of Planck.Headless.Config.openai_api_key/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec preload(Skogsra.Env.namespace()) :: :ok
Preloads all variables in a namespace if supplied.
@spec providers(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.Providers.t()} | {:error, binary()}
Map of named provider entries. Each key is a user-defined provider alias;
the value describes the provider type and connection details. Only readable
from .planck/config.json or application config — no env var equivalent.
Example (in .planck/config.json):
"providers": {
"anthropic": { "type": "anthropic" },
"nvidia": { "type": "openai", "base_url": "https://integrate.api.nvidia.com/v1", "identifier": "NVIDIA" },
"local-ollama": { "type": "openai", "base_url": "http://localhost:11434", "has_api_key": false }
}Calling Planck.Headless.Config.providers() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_PROVIDERS"
- Type: Planck.Headless.Config.Providers
- Default: %{}
- Required: false
- Cached: true
@spec providers!(Skogsra.Env.namespace()) :: Planck.Headless.Config.Providers.t() | no_return()
Map of named provider entries. Each key is a user-defined provider alias;
the value describes the provider type and connection details. Only readable
from .planck/config.json or application config — no env var equivalent.
Example (in .planck/config.json):
"providers": {
"anthropic": { "type": "anthropic" },
"nvidia": { "type": "openai", "base_url": "https://integrate.api.nvidia.com/v1", "identifier": "NVIDIA" },
"local-ollama": { "type": "openai", "base_url": "http://localhost:11434", "has_api_key": false }
}Bang version of Planck.Headless.Config.providers/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec put_anthropic_api_key(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.anthropic_api_key/0. Optionally, receives
the namespace.
@spec put_config_files(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.config_files/0. Optionally, receives
the namespace.
@spec put_default_model(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.default_model/0. Optionally, receives
the namespace.
@spec put_default_provider(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.default_provider/0. Optionally, receives
the namespace.
@spec put_env_files(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.env_files/0. Optionally, receives
the namespace.
@spec put_google_api_key(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.google_api_key/0. Optionally, receives
the namespace.
@spec put_locale(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.locale/0. Optionally, receives
the namespace.
@spec put_models(Planck.Headless.Config.Models.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.models/0. Optionally, receives
the namespace.
@spec put_openai_api_key(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.openai_api_key/0. Optionally, receives
the namespace.
@spec put_providers(Planck.Headless.Config.Providers.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.providers/0. Optionally, receives
the namespace.
@spec put_secrets_hook(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.secrets_hook/0. Optionally, receives
the namespace.
@spec put_sessions_dir(binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.sessions_dir/0. Optionally, receives
the namespace.
@spec put_sidecar(binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.sidecar/0. Optionally, receives
the namespace.
@spec put_skills_dirs(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.skills_dirs/0. Optionally, receives
the namespace.
@spec put_teams_dirs(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.teams_dirs/0. Optionally, receives
the namespace.
@spec put_tool_proxy(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.tool_proxy/0. Optionally, receives
the namespace.
@spec put_tool_proxy_ca_cert(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.tool_proxy_ca_cert/0. Optionally, receives
the namespace.
@spec put_top_skills(integer(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}
Puts the value to Planck.Headless.Config.top_skills/0. Optionally, receives
the namespace.
@spec reload_anthropic_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.anthropic_api_key/0. Optionally, receives
the namespace for the variable.
@spec reload_config_files(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.config_files/0. Optionally, receives
the namespace for the variable.
@spec reload_default_model(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.default_model/0. Optionally, receives
the namespace for the variable.
@spec reload_default_provider(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.default_provider/0. Optionally, receives
the namespace for the variable.
@spec reload_env_files(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.env_files/0. Optionally, receives
the namespace for the variable.
@spec reload_google_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.google_api_key/0. Optionally, receives
the namespace for the variable.
@spec reload_locale(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.locale/0. Optionally, receives
the namespace for the variable.
@spec reload_models(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.Models.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.models/0. Optionally, receives
the namespace for the variable.
@spec reload_openai_api_key(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.openai_api_key/0. Optionally, receives
the namespace for the variable.
@spec reload_providers(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.Providers.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.providers/0. Optionally, receives
the namespace for the variable.
@spec reload_secrets_hook(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.secrets_hook/0. Optionally, receives
the namespace for the variable.
@spec reload_sessions_dir(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.sessions_dir/0. Optionally, receives
the namespace for the variable.
@spec reload_sidecar(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.sidecar/0. Optionally, receives
the namespace for the variable.
@spec reload_skills_dirs(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.skills_dirs/0. Optionally, receives
the namespace for the variable.
@spec reload_teams_dirs(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.teams_dirs/0. Optionally, receives
the namespace for the variable.
@spec reload_tool_proxy(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.tool_proxy/0. Optionally, receives
the namespace for the variable.
@spec reload_tool_proxy_ca_cert(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.tool_proxy_ca_cert/0. Optionally, receives
the namespace for the variable.
@spec reload_top_skills(Skogsra.Env.namespace()) :: {:ok, integer()} | {:error, binary()}
Reloads the value for Planck.Headless.Config.top_skills/0. Optionally, receives
the namespace for the variable.
@spec secrets_hook(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Module that implements Planck.Headless.Secrets for storing and retrieving
API keys. Defaults to Planck.Headless.Secrets.EnvFile (reads/writes
.planck/.env). Set to "Sidecar.Secrets.AgentVault" to store credentials
in agent-vault instead.
Calling Planck.Headless.Config.secrets_hook() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_SECRETS_HOOK"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec secrets_hook!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Module that implements Planck.Headless.Secrets for storing and retrieving
API keys. Defaults to Planck.Headless.Secrets.EnvFile (reads/writes
.planck/.env). Set to "Sidecar.Secrets.AgentVault" to store credentials
in agent-vault instead.
Bang version of Planck.Headless.Config.secrets_hook/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec sessions_dir(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}
Path to the sessions directory.
Calling Planck.Headless.Config.sessions_dir() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_SESSIONS_DIR"
- Type: :binary
- Default: ".planck/sessions"
- Required: false
- Cached: true
@spec sessions_dir!(Skogsra.Env.namespace()) :: binary() | no_return()
Path to the sessions directory.
Bang version of Planck.Headless.Config.sessions_dir/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec sidecar(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}
Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.
Calling Planck.Headless.Config.sidecar() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_SIDECAR"
- Type: :binary
- Default: ".planck/sidecar"
- Required: false
- Cached: true
@spec sidecar!(Skogsra.Env.namespace()) :: binary() | no_return()
Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.
Bang version of Planck.Headless.Config.sidecar/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec skills_dirs(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Colon-separated list of skill directories.
Calling Planck.Headless.Config.skills_dirs() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_SKILLS_DIRS"
- Type: Planck.Headless.Config.PathList
- Default: [".planck/skills", "~/.planck/skills"]
- Required: false
- Cached: true
@spec skills_dirs!(Skogsra.Env.namespace()) :: Planck.Headless.Config.PathList.t() | no_return()
Colon-separated list of skill directories.
Bang version of Planck.Headless.Config.skills_dirs/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec teams_dirs(Skogsra.Env.namespace()) :: {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}
Colon-separated list of team directories.
Calling Planck.Headless.Config.teams_dirs() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_TEAMS_DIRS"
- Type: Planck.Headless.Config.PathList
- Default: [".planck/teams", "~/.planck/teams"]
- Required: false
- Cached: true
@spec teams_dirs!(Skogsra.Env.namespace()) :: Planck.Headless.Config.PathList.t() | no_return()
Colon-separated list of team directories.
Bang version of Planck.Headless.Config.teams_dirs/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec template( Path.t(), keyword() ) :: :ok | {:error, File.posix()}
Creates a template for OS environment variables given a filename.
Additionally, it can receive a list of options:
type: What kind of file it will generate (:elixir,:unix,:windows).namespace: Namespace for the variables.
@spec tool_proxy(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
HTTP proxy URL for all outgoing LLM requests (e.g. "http://vault:14322").
When set, Planck configures its HTTP client to route LLM API calls through
this proxy and sets standard proxy env vars for child processes (bash tools,
sidecar, etc.). Designed for use with credential-injecting proxies such as
agent-vault.
Calling Planck.Headless.Config.tool_proxy() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_TOOL_PROXY"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec tool_proxy!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
HTTP proxy URL for all outgoing LLM requests (e.g. "http://vault:14322").
When set, Planck configures its HTTP client to route LLM API calls through
this proxy and sets standard proxy env vars for child processes (bash tools,
sidecar, etc.). Designed for use with credential-injecting proxies such as
agent-vault.
Bang version of Planck.Headless.Config.tool_proxy/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec tool_proxy_ca_cert(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}
Path to the proxy CA certificate PEM file (e.g. "/certs/ca.pem").
Required when using a TLS MITM proxy such as agent-vault. Planck passes
this to its HTTP client and sets SSL_CERT_FILE/CURL_CA_BUNDLE for
child processes.
Calling Planck.Headless.Config.tool_proxy_ca_cert() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_TOOL_PROXY_CA_CERT"
- Type: :binary
- Default: nil
- Required: false
- Cached: true
@spec tool_proxy_ca_cert!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()
Path to the proxy CA certificate PEM file (e.g. "/certs/ca.pem").
Required when using a TLS MITM proxy such as agent-vault. Planck passes
this to its HTTP client and sets SSL_CERT_FILE/CURL_CA_BUNDLE for
child processes.
Bang version of Planck.Headless.Config.tool_proxy_ca_cert/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec top_skills(Skogsra.Env.namespace()) :: {:ok, integer()} | {:error, binary()}
Maximum number of recently-used skills shown in the agent skill index.
Calling Planck.Headless.Config.top_skills() will ensure the following:
- Binding order: [:system, :config]
- OS environment variable: "PLANCK_TOP_SKILLS"
- Type: :integer
- Default: 5
- Required: false
- Cached: true
@spec top_skills!(Skogsra.Env.namespace()) :: integer() | no_return()
Maximum number of recently-used skills shown in the agent skill index.
Bang version of Planck.Headless.Config.top_skills/0 (fails on error). Optionally,
receives the namespace for the variable.
@spec validate(Skogsra.Env.namespace()) :: :ok | {:error, [binary()]}
Validates that all required variables are present.
Returns :ok if they are, {:error, errors} if they are not. errors
will be a list of all errors encountered while getting required variables.
It is possible to provide a namespace as argument (defaults to nil).
@spec validate!(Skogsra.Env.namespace()) :: :ok | no_return()
Validates that all required variables are present.
Returns :ok if they are, raises if they're not.
It is possible to provide a namespace as argument (defaults to nil).