goose Admin & Architecture Guide

This guide is the deep reference for administrators, platform engineers, and developers who deploy, operate, secure, extend, or embed goose — the open source on-machine AI agent. It covers the system architecture, the full configuration surface, security model, deployment topologies (including remote goosed and Docker), operations, and a source-level internals tour of the Rust workspace and TypeScript desktop app.

For end-user installation and usage, see the companion User Guide.

Table of Contents

1. Executive Summary
2. System Architecture
3. Repository & Workspace Layout
4. The Agent Engine (crates/goose)
5. The goosed Server & Desktop App
6. System Requirements
7. Configuration Mastery
8. Environment Variable Reference
9. Security
10. Deployment
11. Operations
12. Observability
13. Developer Internals
14. Embedding goose (SDKs)
15. Testing Strategy
16. Troubleshooting (Operational)
17. Potential Improvements
18. Quick Reference

1. Executive Summary

goose is a Rust-core, polyglot AI agent distributed as a CLI and a desktop application. Its job is to take a natural-language request, plan with an LLM, and execute real work through tools exposed by Model Context Protocol (MCP) extensions — running commands, editing files, calling APIs — while keeping the operator in control.

What an administrator needs to know up front:

Important

The single most important operational fact: goose executes on the host as the invoking user, with that user's privileges, autonomously by default. Treat the autonomy mode, the extension allowlist, and .gooseignore as your primary control plane (see Security).

2. System Architecture

2.1 Component Model

goose has three logical components, regardless of interface:

• Interface — collects input and renders output (Desktop app, CLI, TUI, or an ACP editor).
• Agent — the core loop (in crates/goose) that orchestrates the model and tools.
• Extensions — MCP servers exposing tools; bundled, third-party, or custom.

 ┌──────────────────────────────────────────────────────────────────────┐
 │                            INTERFACES                                  │
 │                                                                        │
 │  goose CLI        goose Desktop          goose TUI       ACP editors   │
 │  (goose-cli)      (ui/desktop, Electron) (ui/text)       (Zed/JetBrains)│
 │      │                  │  spawns                │  ACP        │ ACP   │
 │      │ in-proc          ▼  + HTTP/WS             │  stdio      ▼       │
 │      │            ┌───────────────┐              │      ┌────────────┐ │
 │      │            │   goosed       │◀─────────────┘      │ goose acp/ │ │
 │      │            │ (goose-server) │  HTTP+WS (X-Secret) │  serve     │ │
 │      │            └──────┬─────────┘                     └─────┬──────┘ │
 └──────┼───────────────────┼─────────────────────────────────────┼──────┘
        │                   │                                      │
        ▼                   ▼                                      ▼
 ┌──────────────────────────────────────────────────────────────────────┐
 │                       AGENT ENGINE  (crates/goose)                     │
 │                                                                        │
 │   Agent loop ── Providers ── Conversation/Context mgmt ── Sessions     │
 │   Recipes ── Scheduler ── Permissions ── Security ── Hooks ── Skills   │
 └───────────────┬───────────────────────────────────┬──────────────────┘
                 │ MCP (rmcp)                         │ Provider HTTP (reqwest/rustls)
                 ▼                                    ▼
 ┌──────────────────────────────┐        ┌──────────────────────────────┐
 │   EXTENSIONS (MCP servers)   │        │       LLM PROVIDERS           │
 │  bundled (goose-mcp):        │        │  Anthropic / OpenAI / Gemini  │
 │   developer, memory,         │        │  Bedrock / Databricks / Groq  │
 │   computercontroller, ...    │        │  Ollama / LM Studio (local)   │
 │  + any 3rd-party / custom    │        │  + 40 more                    │
 └──────────────────────────────┘        └──────────────────────────────┘

2.2 The Agent Loop

A single turn (implemented in crates/goose/src/agents):

1. Request — user input enters via the interface.
2. Provider chat — the agent sends the request plus the catalogue of available tools to the configured LLM provider.
3. Tool call — the model may return a tool call (JSON). The model describes the action; goose executes it.
4. Execute — the agent dispatches the call to the owning MCP extension and collects the result.
5. Feed back — results return to the model; tool steps repeat as needed.
6. Context revision — old/irrelevant content is dropped, verbose output summarized, to manage tokens and cost.
7. Response — the model's final answer is rendered; the loop restarts on the next message.

Resilient error handling: invalid JSON, missing tools, and command failures are returned to the model as tool results (becoming "prompts" that let it self-correct) rather than aborting the session.

2.3 Key Protocols & Foundations

3. Repository & Workspace Layout

The repository is a Cargo workspace (crates/*) plus separately-built TypeScript apps under ui/, a Docusaurus docs site, and supporting tooling.

3.1 Rust Crates (layered by responsibility)

Note

A *-macros/proc-macro crate (goose-acp-macros) plus a thin facade (goose-sdk over goose) is the classic Rust workspace shape: the macro crate enforces compile-time guarantees for the protocol layer, and the SDK re-exports the engine for embedders. Read each member's Cargo.toml for its exact description and target-specific dependencies.

3.2 Non-Crate Components

3.3 Build Tooling

• Justfile — task runner (just generate-manpages, build helpers, etc.).
• Dockerfile, BUILDING_DOCKER.md, BUILDING_LINUX.md — container & Linux builds.
• CUSTOM_DISTROS.md — building custom/branded goose distributions.
• flake.nix — Nix dev environment.
• rust-toolchain.toml — pins the Rust toolchain (MSRV 1.91.1).

4. The Agent Engine (crates/goose)

crates/goose/src is the system's core. Key modules (an operator/extender's map):

4.1 The Extension/Tool Contract

Extensions implement a Rust Extension trait (for bundled extensions) or speak MCP over stdio/Streamable HTTP (for external ones). The trait:

#[async_trait]
pub trait Extension: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn instructions(&self) -> &str;
    fn tools(&self) -> &[Tool];
    async fn status(&self) -> AnyhowResult<HashMap<String, Value>>;
    async fn call_tool(&self, tool_name: &str,
                       parameters: HashMap<String, Value>) -> ToolResult<Value>;
}

Each tool is async, takes a JSON Value, and returns a ToolResult<Value>. Errors come in two flavors: ErrorData (tool-execution errors that are surfaced back to the model as prompts) and anyhow::Error (general extension errors). This split is deliberate — tool errors become part of the conversation so the model can recover.

Tip

When building a bundled extension, return specific ErrorData messages — they become prompts the model reads. Vague errors waste a turn; precise ones ("file not found at /x; did you mean /y?") let the model self-correct immediately.

5. The goosed Server & Desktop App

5.1 What goosed Is

goosed (built from crates/goose-server) is an Axum HTTP + WebSocket server that exposes the agent engine as an API. The Desktop app spawns goosed as a local subprocess and drives it over HTTP/WebSocket. goosed is also what goose serve runs for ACP-over-HTTP.

5.2 The goosed API Surface

Routes live in crates/goose-server/src/routes/. They are not a public, unauthenticated API — every request requires the shared secret in the X-Secret-Key header (see below). Route groups:

5.3 Securing goosed

Every client request must carry the shared secret:

# A network-reachable goosed over TLS with a fixed secret
export GOOSE_HOST=0.0.0.0
export GOOSE_PORT=3000
export GOOSE_TLS=true
export GOOSE_SERVER__SECRET_KEY='a-long-random-secret'
goosed agent

Caution

Binding goosed to 0.0.0.0 exposes an agent that can execute commands on the host to the network. Always keep TLS on, set a strong GOOSE_SERVER__SECRET_KEY, and restrict access at the network layer (firewall/VPN). On startup with TLS, goosed prints GOOSED_CERT_FINGERPRINT=...; clients need it to verify the self-signed cert. See Remote goose Server.

5.4 The Desktop App

ui/desktop is an Electron + React (TypeScript) app. It:

• Locates and spawns the goosed binary (GOOSED_BINARY, GOOSE_EXTERNAL_BACKEND, GOOSE_PORT).
• Talks to goosed over the local HTTP/WS API.
• Handles desktop concerns: auto-update (autoUpdater.ts, githubUpdater.ts), proxy settings (HTTP_PROXY/HTTPS_PROXY/NO_PROXY), deep links (goose://), localization, and platform shims (Windows winShims.ts).
• Shares all core config with the CLI via the same config.yaml and keyring, so settings made in one surface apply to the other.

6. System Requirements

Note

goose stores data per-platform: macOS ~/Library/Application Support/Block/goose/, Linux ~/.local/share/goose/, Windows %APPDATA%\Block\goose\. Config lives in ~/.config/goose/ (macOS/Linux) or %APPDATA%\Block\goose\config\ (Windows). Override the root with GOOSE_PATH_ROOT.

7. Configuration Mastery

7.1 Configuration Files

Locations: ~/.config/goose/ (macOS/Linux) or %APPDATA%\Block\goose\config\ (Windows).

7.2 Configuration Precedence

1. Environment variables   (highest priority)
2. config.yaml settings
3. Built-in defaults       (lowest priority)

7.3 A Complete config.yaml

# --- Model Configuration ---
GOOSE_PROVIDER: "anthropic"
GOOSE_MODEL: "claude-4.5-sonnet"
GOOSE_TEMPERATURE: 0.7

# --- Planning (optional separate model) ---
GOOSE_PLANNER_PROVIDER: "openai"
GOOSE_PLANNER_MODEL: "gpt-4"

# --- Tool / autonomy behavior ---
GOOSE_MODE: "smart_approve"        # auto | approve | smart_approve | chat
GOOSE_TOOLSHIM: true
GOOSE_CLI_MIN_PRIORITY: 0.2

# --- Recipes ---
GOOSE_RECIPE_GITHUB_REPO: "aaif-goose/goose-recipes"

# --- Extension command search path ---
GOOSE_SEARCH_PATHS:
  - "/usr/local/bin"
  - "~/custom/tools"
  - "/opt/homebrew/bin"

# --- Security ---
SECURITY_PROMPT_ENABLED: true

# --- Observability ---
otel_exporter_otlp_endpoint: "http://localhost:4318"
otel_exporter_otlp_timeout: 20000

# --- Custom slash commands that run recipes ---
slash_commands:
  - command: "run-tests"
    recipe_path: "/path/to/recipe.yaml"

# --- Extensions ---
extensions:
  developer:
    bundled: true
    enabled: true
    name: developer
    timeout: 300
    type: builtin
  memory:
    bundled: true
    enabled: true
    name: memory
    timeout: 300
    type: builtin
  github:
    name: GitHub
    type: stdio
    cmd: npx
    args: [-y @modelcontextprotocol/server-github]
    enabled: true
    timeout: 300
    envs: { "GITHUB_PERSONAL_ACCESS_TOKEN": "<TOKEN>" }
    available_tools: []      # empty = all tools; or restrict to specific tool names

7.4 Global Settings (root of config.yaml)

* The default mode is smart_approve at runtime; config.yaml documents auto as the file default. Set it explicitly to avoid ambiguity.

7.5 Extension Configuration Schema

extensions:
  <name>:
    bundled: true|false        # included with goose
    display_name: "Name"       # human-readable (optional)
    enabled: true|false        # active?
    name: "<name>"             # internal name
    timeout: 300               # per-tool-call timeout (seconds)
    type: "builtin"|"stdio"|"streamable_http"
    available_tools: []        # [] = all tools; or a whitelist of tool names

    # stdio extensions only:
    cmd: "command"
    args: ["arg1", "arg2"]
    description: "text"
    env_keys: []
    envs: {}

Tip

Tool filtering via available_tools is an under-used token optimization: load only the tools you need from a big extension to cut prompt overhead. Empty means all tools.

7.6 Verifying Configuration

goose info -v          # all active settings and current values
goose info --check     # test the provider connection
goose doctor           # end-to-end health check

Note

Direct edits to config files usually require restarting goose for existing sessions. Provider credential changes made through Desktop Settings refresh the provider inventory without a restart, but currently-active chat sessions keep the provider instance they started with.

8. Environment Variable Reference

Environment variables override config.yaml. Grouped by function.

8.1 Model & Provider

8.2 Session & Context

8.3 Tools & Execution

8.4 Security & Privacy

8.5 Network, Server & OAuth

8.6 Observability

8.7 Recipes & Internal

Important

Enterprise rollout: For consistent governance, pre-set provider endpoints (GOOSE_PROVIDER__HOST), proxy variables, GOOSE_ALLOWLIST, and security toggles via your configuration management, and prefer the keyring or env vars over committing secrets to secrets.yaml.

9. Security

goose's threat model is unusual: it is an agent that executes arbitrary actions on the host as the user, directed by an LLM that may be influenced by untrusted content (web pages, file contents, tool output). The controls below form the defense.

9.1 The Autonomy Control Plane

Caution

Default mode is smart_approve, not read-only. For shared, CI, or high-privilege hosts, set GOOSE_MODE=approve or chat and scope .gooseignore to keep goose away from secrets, infra config, and credential stores.

9.2 Extension Malware Scanning

Locally-executed external extensions installed via uvx (PyPI) or npx (NPM) are checked against the OSV malware database before activation. A hit is blocked:

Blocked malicious package: package-name@1.0.0 (npm). OSV MAL advisories: MAL-2024-1234

If the OSV service is unreachable, extensions still install (fail-open) — so the allowlist remains your hard control. Only install extensions from trusted sources.

9.3 Prompt-Injection Detection

goose can scan for prompt-injection attempts (malicious instructions hidden in content goose reads):

export SECURITY_PROMPT_ENABLED=true
export SECURITY_PROMPT_THRESHOLD=0.9             # stricter
# Optional ML-based classifier:
export SECURITY_PROMPT_CLASSIFIER_ENABLED=true
export SECURITY_PROMPT_CLASSIFIER_ENDPOINT="https://your-endpoint/classify"
export SECURITY_PROMPT_CLASSIFIER_TOKEN="..."

9.4 Secret Storage

• Default: OS keyring (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux) via the keyring crate.
• Fallback: secrets.yaml (plaintext) when no keyring is available (headless, containers, CI) or when disabled with GOOSE_DISABLE_KEYRING.

GOOSE_DISABLE_KEYRING=1 goose configure

Warning

secrets.yaml stores keys in plaintext. In CI/containers prefer injecting provider keys as environment variables and answering No to "save to keyring," rather than persisting secrets.yaml.

9.5 macOS Desktop Sandbox

The Desktop app supports an optional macOS sandbox using Apple's sandbox-exec to restrict file access, network connections, and process execution:

export GOOSE_SANDBOX=true

9.6 goosed Network Exposure

See §5.3. The combination that matters: TLS on + strong GOOSE_SERVER__SECRET_KEY + network-layer restriction whenever GOOSE_HOST is not 127.0.0.1.

9.7 Reporting

Security issues are handled per SECURITY.md in the repository. Do not file public issues for vulnerabilities.

10. Deployment

10.1 Desktop Deployment

Distribute the platform build (macOS app, Linux DEB, Windows package) or via package managers (brew install --cask block-goose). The Desktop self-updates; ENABLE_DEV_UPDATES/GOOSE_VERSION control update channels for testing.

10.2 CLI Deployment (incl. CI/CD)

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

For reproducible, non-interactive installs (CI/CD), pin the version to avoid 404s when the stable tag lacks assets:

export GOOSE_VERSION=1.37.0

A headless CI run:

export GOOSE_PROVIDER=anthropic GOOSE_MODEL=claude-sonnet-4-5
export ANTHROPIC_API_KEY=...           # via secret store, not secrets.yaml
export GOOSE_DISABLE_KEYRING=1
export GOOSE_MODE=auto
goose run --no-session --recipe ci-check.yaml --output-format json

10.3 Remote goosed Server

Run goosed on a remote/more-powerful host and connect the Desktop to it:

# On the remote host
export GOOSE_HOST=0.0.0.0 GOOSE_PORT=3000 GOOSE_TLS=true
export GOOSE_SERVER__SECRET_KEY='a-long-random-secret'
goosed agent
# Note the printed GOOSED_CERT_FINGERPRINT=... — the client needs it

The Desktop then connects with the host, port, secret, and cert fingerprint. Restrict access with a firewall/VPN.

10.4 Docker / DevContainers

goose can run inside containers, and can run extensions inside a container via --container <id> (for devcontainer workflows). See BUILDING_DOCKER.md and the in-repo Dockerfile. In containers, the keyring is typically unavailable — set GOOSE_DISABLE_KEYRING=1 and inject keys via env vars.

10.5 Custom Distributions

CUSTOM_DISTROS.md documents building branded/customized goose builds — useful for enterprises that need to bake in proxy config, an allowlist, custom shims for airgapped networks, or a pre-pinned provider.

10.6 Linux Packaging & Manpages

Distribution packagers can generate Unix manpages from the CLI definitions:

just generate-manpages    # ROFF output in target/man/ (goose.1, goose-session.1, ...)

Install them to /usr/share/man/man1/ for offline man goose. See BUILDING_LINUX.md.

11. Operations

11.1 Health & Diagnostics

goose doctor              # full health check
goose info -v             # active config
goose info --check        # provider connectivity
goose session diagnostics --name <session> -o diag.zip   # support bundle

11.2 Logs & Data Locations

11.3 Scheduled Jobs

The built-in scheduler runs recipes on cron (no external service):

goose schedule add --schedule-id nightly --cron "0 2 * * *" --recipe-source ~/recipes/maint.yaml
goose schedule list
goose schedule run-now --schedule-id nightly
goose schedule remove --schedule-id nightly

11.4 Backup & Migration

Back up ~/.config/goose/ (config + recipes + prompts) and the data directory (sessions). Secrets live in the OS keyring (or secrets.yaml if file-based). Use GOOSE_PATH_ROOT to relocate or isolate an entire environment.

11.5 Uninstall / Reset

Stop all goose processes, delete the "goose" credential from the keychain/credential manager, then remove the data/config/state directories for your platform (see Known Issues → Uninstall).

12. Observability

goose emits OpenTelemetry signals (traces, metrics, logs) to any OTLP-compatible collector, has a Langfuse integration, and an opt-in PostHog telemetry channel.

# Export everything to a local collector
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

# Traces only; console debug; sample 10% in prod
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"
export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.1"

Or in config.yaml:

otel_exporter_otlp_endpoint: "http://localhost:4318"
otel_exporter_otlp_timeout: 20000

Built-in metrics include session counters, durations, token usage, and recipe runs (emitted as monotonic_counter.goose.* tracing events). Anonymous product telemetry is off by default (GOOSE_TELEMETRY_ENABLED=false).

Tip

For per-session LLM tracing (prompts, tool calls, costs), use the Langfuse integration (LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY) — the most operator-friendly view of what the agent actually did.

13. Developer Internals

13.1 Architecture Layers (recap, for extenders)

goose-cli / ui/desktop / ui/text / ACP editors      ← interfaces
            │
crates/goose-server (goosed, Axum)                  ← API surface (Desktop/ACP-HTTP)
            │
crates/goose                                         ← engine (loop, providers, MCP, recipes,
            │                                          sessions, scheduler, security, permissions)
            ├── MCP (rmcp) → goose-mcp + 3rd-party    ← tools
            └── provider HTTP → LLM providers          ← models
crates/goose-sdk(+types), goose-acp-macros           ← embedding & protocol support

13.2 Provider Layer

Providers live in crates/goose/src/providers/, one module per provider, plus:

• declarative/*.json — model catalogs (e.g. groq.json, novita.json, routstr.json) listing model names and context limits. This is where the "supported models per provider" data lives.
• local_inference/ — GGUF inference via llama-cpp-2 (with a llamacpp/ backend) and candle.
• formats/, canonical/ — request/response formatting and a canonical message representation that normalizes across providers.

To add a provider, implement the provider trait, add a declarative model catalog if applicable, and register it. Prompt caching for Claude is applied automatically for Anthropic/Bedrock/Databricks/OpenRouter/LiteLLM.

13.3 Recipes & Scheduler

• recipe/ parses and templates recipe YAML (Jinja-style includes, parameters, sub-recipes) and builds deeplinks (recipe_deeplink.rs).
• scheduler.rs + scheduler_trait.rs implement the embedded cron scheduler (no external broker).

13.4 Context Management

context_mgmt/ and conversation/ implement the context-revision strategy: token counting (token_counter.rs), automatic compaction (GOOSE_AUTO_COMPACT_THRESHOLD), tool-output summarization (GOOSE_TOOL_CALL_CUTOFF), and find-and-replace-over-rewrite editing. This is the cost-control core.

13.5 Code Mode & V8

The Code Mode platform extension executes JavaScript for tool discovery/calling. It relies on a vendored V8 (vendor/v8, pinned via [patch.crates-io]) — a notable build dependency. Known interaction bug: MCP Apps may fail to render when Code Execution is enabled (#9598).

13.6 Contributing

See CONTRIBUTING.md, CONTRIBUTING_RECIPES.md, AGENTS.md (agent-oriented contribution guidance), GOVERNANCE.md, MAINTAINERS.md, and RELEASE.md/RELEASE_CHECKLIST.md. The project moved to the AAIF organization (aaif-goose/goose); authorship is AAIF <[email removed]>, license Apache-2.0.

14. Embedding goose (SDKs)

Two SDK surfaces let you embed goose:

• Rust SDK — crates/goose-sdk (types in crates/goose-sdk-types), including UniFFI bindings (examples/uniffi) so the agent can be driven from other languages.
• TypeScript SDK — ui/sdk, a generated client (src/generated/) for the goosed HTTP API. This is what custom front-ends or integrations target.

Embedders typically run goosed (or link the engine) and drive sessions/recipes through these clients, supplying provider config and extensions programmatically.

15. Testing Strategy

Extensions should be tested at three levels: unit tests per tool, integration tests for extension behavior, and property tests for tool invariants.

16. Troubleshooting (Operational)

16.1 Keyring Unavailable (containers / headless / CI)

Symptom: Failed to access keyring / org.freedesktop.secrets was not provided. Cause: No desktop keyring (Secret Service over DBus) in the environment. Fix: Force file storage or use env vars:

GOOSE_DISABLE_KEYRING=1 goose configure

goose may auto-fall-back to secrets.yaml for the current process; new sessions retry the keyring. Force file storage to make it persistent.

16.2 Airgapped / Restricted Networks

Symptom: Extensions fail with hermit:fatal or "Could not run extension command." Cause: goose's packaged npx/uvx shims try to download runtimes via Hermit, which restricted networks block. Fix: Create alternatively-named runners (not npx/uvx/jbang) so goose passes them through unchanged, and reference those in config:

ln -s /usr/local/bin/uvx /usr/local/bin/runuv
ln -s /usr/local/bin/npx /usr/local/bin/runnpx

extensions:
  example:
    cmd: runuv          # bypasses goose's shim
    args: [mcp-server-example]

For deeper constraints (TLS interception, proxies), build a custom distribution (CUSTOM_DISTROS.md) with the right shims/config baked in.

16.3 Clean Uninstall / Reset

Stop all goose processes, delete the "goose" keychain/credential, then:

# macOS
rm -rf ~/.config/goose ~/Library/Application\ Support/goose
# Linux
rm -rf ~/.local/share/goose/ ~/.local/state/goose/ ~/.config/goose/
# Windows (cmd)
rmdir /s /q "%APPDATA%\Block\goose"
rmdir /s /q "%LOCALAPPDATA%\Block\goose"

16.4 Corporate Proxy

export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal"

Restart goose. Env vars take precedence over OS proxy settings.

16.5 OAuth Behind a Strict IdP

If your identity provider requires an exact redirect_uri (no wildcard ports), pin the callback port:

export GOOSE_OAUTH_CALLBACK_PORT=8080

Register http://127.0.0.1:8080/oauth_callback (MCP OAuth) or http://localhost:8080 (Databricks OAuth).

16.6 Node.js Extensions Fail on Windows

goose expects Node at C:\Program Files\nodejs\. If installed elsewhere, symlink it (Admin PowerShell): mklink /D "C:\Program Files\nodejs" "D:\Program Files\nodejs".

16.7 Known Bugs (from the issue tracker)

17. Potential Improvements

Observations for maintainers and operators planning hardening or contributions:

• Default mode clarity. config.yaml documents GOOSE_MODE default as auto while runtime default is smart_approve. Aligning the documented and effective defaults would reduce operator surprise on high-privilege hosts.
• secrets.yaml plaintext. File-based fallback stores secrets unencrypted. An at-rest encryption option (or first-class env-injection mode) would help container/CI deployments that can't use a keyring.
• Fail-open malware scan. If OSV is unreachable, extension installs proceed. Environments with a strict posture should treat the allowlist as the authoritative control and consider a fail-closed option.
• goosed exposure footguns. Binding to 0.0.0.0 exposes a command-executing agent; a startup warning when GOOSE_HOST != 127.0.0.1 without a strong secret would reduce risk.
• Code Mode / MCP Apps interaction (#9598). A documented, enforced mutual exclusion (or a fix) would remove a sharp edge.
• Windows ACP shell stdout (#9582). Empty stdout/stderr under ACP stdio is a correctness gap for Windows automation.
• Tree-sitter breadth. Code intelligence covers 10 languages; extending the grammar set would broaden Code Mode/analysis coverage.

18. Quick Reference

18.1 Operator Commands

goose doctor                 # health check
goose info -v                # full config
goose info --check           # provider connectivity
goosed agent                 # run the server (Desktop backend / remote)
goose serve --port 3284      # ACP over HTTP/WS
goose schedule list          # scheduled jobs
just generate-manpages       # packager manpages

18.2 Critical Security Settings

18.3 Workspace Crate Map

18.4 Facts Sheet