Skip to content

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.