Configuration¶
Configure settings where work executes. A remote client needs the server URL and token; the server owns model, tool, and skill configuration. CLI options override corresponding environment settings.
Model¶
Set LANDING_* variables or save YAML in ~/.landing/config.yml. LANDING_CONFIG selects another file. Empty environment values are ignored; YAML null clears an optional setting.
| Variable | Contract |
|---|---|
LANDING_MODEL |
Provider/model identifier, such as openai:gpt-4.1. |
LANDING_API_KEY |
Selected provider's API key. |
LANDING_API_BASE |
Optional endpoint; unset uses the provider default. |
LANDING_MODEL_TIMEOUT_SECONDS |
Model request timeout in seconds. |
LANDING_COMPLETION_ARGS |
Provider completion options as a JSON object. |
LANDING_CLIENT_ARGS |
Provider client options as a JSON object, such as {"api_format": "chat"}. |
LANDING_MAX_TOKENS |
Maximum generated tokens, default 16384. |
LANDING_FALLBACK_MODELS |
Fallback identifiers as a JSON list. |
LANDING_CONFIG |
YAML settings path. |
export LANDING_MODEL="openai:gpt-4.1"
export LANDING_API_KEY="your-provider-api-key"
YAML uses lowercase names without the prefix:
model: openai:gpt-4.1
api_key: your-provider-api-key
completion_args:
temperature: 0.2
Precedence is environment, Landing YAML, then defaults. Bub loads Landing's YAML and resolves registered component settings. Configure provider protocols and clients through Republic options in client_args; for a Chat Completions endpoint, use api_format: chat. Model clients use Bub's native provider credential resolution when explicit credentials are absent.
Skills¶
| Setting | Contract |
|---|---|
YAML skill_dirs |
Additional trusted roots as a list of paths. |
LANDING_SKILL_DIRS |
The same roots as a JSON list. |
Global --skill-dir PATH |
Repeatable per-call or server roots. |
Discovery precedence is workspace .agents/skills, explicit roots, configured roots, ~/.agents/skills, then bundled skills. Explicit roots add to configured roots; duplicate skill names select the earlier root. Prepare roots on the executing host; remote clients cannot supply local directories. See Prepare skills.
Mode capabilities¶
YAML modes or JSON LANDING_MODES configures additional instructions and allowed or excluded tools and skills independently for each mode:
modes:
issuer:
allowed_tools: [spill.read, fs.read, bash, skill, no_update]
allowed_skills: [landing-issuer, issue-triage]
fixer:
allowed_tools: [spill.read, fs.read, fs.write, fs.edit, bash, skill]
allowed_skills: [landing-fixer, friendly-python, piglet]
gatekeeper:
instructions: |
Review supported user-visible behavior.
Use $landing-review for project-specific standards.
allowed_skills: [landing-gatekeeper, landing-review]
excluded_tools: [fs.write, fs.edit]
explainer:
allowed_tools: [spill.read, fs.read, skill]
allowed_skills: [landing-explainer, documentation-writer]
instructions adds guidance without replacing the selected method or granting capabilities. Keep project conventions in AGENTS.md, reusable methods in skills, and evidence in task inputs. These additions stay literal rather than being evaluated as templates.
Same-named skill overrides resolve before filtering. Capabilities follow this rule:
Available capabilities ∩ Mode allow list − Mode exclusions
Omitted or null allow lists are unrestricted; [] disables the collection. Exclusions default to empty lists and win over allow lists. Tool lists accept native names or aliases such as fs.read and fs_read; skill names are case-insensitive.
Each mode automatically uses its permitted landing-{mode} skill. Include that name in allow lists to retain its method. Excluding it disables the method while preserving the mode, checks, and publication requirements. A same-named skill in a higher-priority root replaces it. Allowing a skill grants no tools.
Include skill to load supplementary skills, spill.read for oversized output, decide for review recommendations, and no_update for quiet issuer completion. GitHub publication normally requires bash and authenticated gh; inline replies also require confirm_reply.
Filters control method loading and model tool calls across entry points. They do not grant publishing authority, isolate the filesystem, disable required checks, or erase history. Excluded skills are omitted from the task's skill listing. Enforce permissions and isolation in tools and the execution environment.
MCP servers¶
LANDING_MCP_CONFIG or YAML mcp_config selects a trusted mcp.json file; relative paths resolve from the task workspace. An explicit missing file fails the task. Without an explicit path, Landing selects the first existing workspace .agents/mcp.json, user ~/.agents/mcp.json, or native bub-mcp configuration path (normally ~/.bub/mcp.json). Files replace one another rather than merging; an empty mcpServers mapping disables servers. Missing default files leave MCP disabled.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["--yes", "@playwright/mcp@0.0.83", "--headless", "--isolated"]
}
}
}
Use the mcpServers JSON format shown above. Native YAML mcp.config_path configures the final fallback, mcp.init_timeout_seconds controls connection startup, and mcp.deferred_tools: false offers server tools directly instead of loading them on demand. Server commands run in their prepared environment; use absolute command, argument, and output paths when working across repositories.
Discovered tools use names such as mcp.playwright_browser_navigate and load on demand: the task prompt lists the names its mode allows, the model calls tool_describe with one, and the tool stays callable by name for the rest of the session. The SDK supplies tool_describe alongside a deferred list, so mode tool limits apply before loading and excluded tools never reach the model. A configured server that cannot connect fails the task before model work; connection details remain in runner logs. See Use MCP servers for setup and an example.
Execution and service¶
| Variable | Contract |
|---|---|
LANDING_DB |
SQLite path, default ~/.local/share/landing/landing.sqlite3; image default /storage/landing.sqlite3. |
LANDING_TOKEN |
Server bearer token; required to listen beyond localhost. |
LANDING_REPLICATE |
Supervise standalone serve with installed Litestream, default false; image default true. |
LANDING_GITHUB_REPOSITORY |
Prepared gh repository context. |
LANDING_BASE_URL |
Public HTTP(S) origin for pagination; no credentials, path, query, or fragment. |
CLI and service settings read their own fields from environment and Landing YAML. YAML keys are db, token, replicate, github_repository and base_url. CLI options override corresponding settings. MCP settings load when a task prepares its tools, and configuration errors remain visible in its action record.
Local workspace defaults to the current directory. Servers register names with serve --workspace NAME=PATH.
GitHub workflows and runner¶
The runner uses prepared GH_TOKEN or gh login for publication and optional GH_ADMISSION_TOKEN for separate admission. Action inputs load from INPUT_*; explicit CLI options take precedence. Checks and upstream workflow names use multiline inputs. Native GITHUB_* identity and event context come from the execution environment; YAML cannot grant caller authority. An empty checked-revision input leaves check provenance unknown.
Commit attribution uses Git configuration or GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. Selecting a publication token alone does not change commit attribution. See GitHub integration for identity and trust, and Action inputs for invocation.
Container replication¶
| Variable | Contract |
|---|---|
LITESTREAM_REPLICA_URL |
Replica destination; Compose defaults to file:///replica/landing. |
LITESTREAM_CONFIG |
Optional mounted standard configuration path. |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION |
Credentials and region for the corresponding storage provider. |
Compose forwards only variables listed in compose.yaml, including model, key, endpoint, completion/client options, and model timeout. Add other settings or mounts through an override; exporting them on the host alone does not forward them. See Deployment and Recovery.