Otto settings

This page is the reference for every place Otto reads configuration from. For deep dives on specific subsystems, see Permissions, Extensions, Memory, and Skills.

File layout

Otto reads from your project repository and your home directory:

your-project/                          # Astro project root
├── .agents/
│   └── skills/                        # Project skills shared across agent harnesses
│       └── <skill-name>/SKILL.md
└── .astro/
    ├── config.yaml                    # Astro CLI project config (Otto reads otto.* and dev.mode)
    ├── memory/                        # Shared project memory (committed, team-visible)
    │   ├── MEMORY.md
    │   └── *.md
    └── otto/
        ├── permissions.json           # Allow, ask, and deny rules
        ├── extensions.json            # Per-project extension toggles
        └── skills/                    # Project skills authored by your team
            └── <skill-name>/SKILL.md
~/                                     # Your home directory
├── .agents/
│   └── skills/                        # User skills shared across agent harnesses
│       └── <skill-name>/SKILL.md
├── .astro/
│   ├── config.yaml                    # Astro CLI global config
│   ├── bin/
│   │   └── otto                       # Otto binary, downloaded on first launch
│   ├── memory/
│   │   ├── MEMORY.md                  # Local user memory (all projects, this computer)
│   │   ├── *.md
│   │   └── <project-slug>/            # Local project memory (this project, this computer)
│   │       └── *.md
│   └── otto/
│       ├── settings.json              # Otto user settings
│       ├── sessions/                  # Session history (JSONL)
│       ├── skills/                    # User skills authored by you
│       │   └── <skill-name>/SKILL.md
│       ├── cache/skills/              # Hosted skill cache (1-hour TTL)
│       └── logs/cli.log               # CLI-side log (rotates at 1 MiB)

Settings precedence

When the same setting is defined in multiple places, Otto resolves it in this order, with earlier entries overriding later ones:

1. CLI flag passed to astro otto (for example, --model, --allowed-tools, --no-extension)
2. Environment variable (for example, OTTO_DISABLED_EXTENSIONS)
3. Project file (.astro/otto/permissions.json, .astro/otto/extensions.json, .astro/config.yaml)
4. User file (~/.astro/otto/settings.json, ~/.astro/config.yaml)
5. Built-in default

Environment variables

The astro otto command sets several environment variables automatically based on your astro login context and the current project. You don’t need to configure these manually.

The CLI also keeps your Astro access token refreshed in the background for the duration of the session, so long-lived sessions don’t hit authentication errors.

You can set the following variables yourself to control Otto behavior:

Auto-update

The first time you run astro otto, the Astro CLI downloads the Otto binary to ~/.astro/bin/otto. After that, the CLI checks for new Otto releases once per day in the background and prints a hint to stderr when an update is available. Updates are applied manually with astro otto update.

Otto versions independently of the Astro CLI. You don’t need to upgrade the Astro CLI to pick up new Otto features or fixes. Check your installed version with astro otto version.

To opt out of the daily update check, set astro config set -g otto.auto_update false.

See also

• Permissions — Allow, ask, and deny rules for tool calls.
• Extensions — Toggle bundled extensions.
• Memory — Memory tiers and file format.
• Skills — Skill catalog and local skill authoring.
• astro otto CLI reference — Flags and subcommands.
• Configure the Astro CLI — Full Astro CLI config reference.