How to Install Fugu in Codex: Full Setup, Flags & Backups

The Codex integration is the most complete way to run Sakana Fugu in a coding agent: a launcher that keeps your config current, a version-pinned Codex known to work with Fugu’s configs, and a real backup system for everything it touches. This guide covers the one-line install, every launcher flag, the full manual setup, and how version pinning and backups behave. All of it verified against Sakana’s official repository and get-started page on August 19, 2026.

The one-line install

curl -fsSL https://sakana.ai/fugu/install | bash

The bootstrap clones the repo to ~/.fugu, then asks whether to set up Codex, Claude Code, or both (Codex-only: append -s -- --codex; it’s also the headless default). The Codex installer then pins the Codex CLI, deploys the Fugu config, and stores your fish_ API key. Non-interactive, for CI or provisioning:

curl -fsSL https://sakana.ai/fugu/install | SAKANA_API_KEY=your_key FUGU_INSTALL_TARGET=codex bash -s -- --yes

Supported platforms: Ubuntu and macOS (Windows: see the Windows guide). Afterwards, launch with:

codex-fugu

which runs codex -p fugu — Codex with the Fugu profile — plus an hourly config-update check that never blocks launch.

Version pinning: why your Codex version may change

Fugu’s configs are verified against a specific Codex version — 0.147.0 as of August 19, 2026, per the repo’s release notes. On a mismatch, the installer offers to switch your Codex binary to the pinned version, and the launcher offers the same reconcile at most once an hour. A switch only ever happens with your consent (an interactive yes, or --force).

One side effect to know: Codex keeps a per-version session index, so after a version switch, codex resume lists different past sessions. Your transcripts under ~/.codex/sessions are never deleted — only which sessions the resume list shows changes. To get an earlier resume list back, run the Codex version that wrote it, or restore the saved session index from a backup:

cp -p ~/.codex-backups/codex-config-<timestamp>/*.sqlite* ~/.codex/

To pin a different Codex version, use --pinned-version X.Y.Z on the installer (or the FUGU_PINNED_VERSION / CODEX_RELEASE environment variables).

Launcher flags

Flag	What it does
--status	Show installed version, pinned target, and update state
--set-key	Rotate the stored Sakana API key
--check	Check for a config update now, instead of waiting for the hourly check
--recheck	Re-enable update prompts you previously dismissed, then check
--no-update	Skip the update check for this launch

Launcher flags are read only when they come first; from the first other argument on, everything is forwarded unchanged to codex -p fugu. So codex-fugu resume resumes a session, codex-fugu "fix the failing test" starts one with a prompt, and codex-fugu --no-update resume combines both. Set CODEX_FUGU_NO_UPDATE=1 to disable update checks permanently, and CODEX_FUGU_NO_NOTICE=1 to silence the launcher’s occasional one-time notices.

Manual setup, file by file

Prefer to see exactly what you’re running? Three files wire Codex to Fugu. (You can also clone the repo yourself and run bash ~/.fugu/scripts/install.sh to do the same steps without the hosted endpoint.)

1. The model catalog — ~/.codex/fugu.json. Copy it from Sakana’s get-started page or the repo (configs/files/fugu.json). As of August 19, 2026 it defines four models: fugu (efforts high/xhigh), fugu-ultra-v1.1 (high/xhigh/max — the only model with a distinct max level), fugu-ultra-v1.0 (high/xhigh), and fugu-cyber (high/xhigh) — all with 1,000,000-token context windows. Note there is no unversioned fugu-ultra entry anymore: since an August update, the picker lists explicit versions so a new Ultra release never changes the model under you.

2. The profile — ~/.codex/fugu.config.toml:

model = "fugu"
model_reasoning_effort = "high"
model_provider = "sakana"
model_catalog_json = "~/.codex/fugu.json"

[features]
image_generation = false
apps = false

(The installer-deployed version of this file also sets remote_plugin = false in the features block — Sakana has pinned remote plugins off since Codex began enabling them by default; remove that line if you want upstream’s behavior.)

3. The provider block — appended to ~/.codex/config.toml (a workspace-local .codex/config.toml works too). The last three keys are stream-resilience hardening, which Sakana documents as verified safe because Fugu is stateless and retries are idempotent:

[model_providers.sakana]
name = "Sakana API"
base_url = "https://api.sakana.ai/v1"
env_key = "SAKANA_API_KEY"
wire_api = "responses"
stream_idle_timeout_ms = 7200000  # keep slow turns alive past Codex's ~5-min idle default
stream_max_retries = 5            # reconnect a dropped stream rather than failing the turn
request_max_retries = 4           # retry a transient HTTP failure rather than failing the turn

Then start Codex with your key in the environment:

SAKANA_API_KEY={your api key} codex -p fugu

It defaults to fugu; switch models any time with /model. That long stream timeout isn’t decoration, by the way — Fugu Ultra’s multi-agent turns can genuinely run long, and the default ~5-minute idle cutoff would kill them.

Backups: what’s saved and how to restore

Before switching your Codex version or first editing config.toml, the installer saves a timestamped copy of your existing setup to ~/.codex-backups/codex-config-<timestamp>/ — deliberately outside ~/.codex, so a backup survives even a full rm -rf ~/.codex. Each backup holds your config.toml and any *.config.toml, auth.json (kept at mode 0600), catalog JSON and Markdown files, the session index (state/memories/goals SQLite files), plus a manifest and SHA-256 checksums. The ten most recent backups are kept; tune with CODEX_BACKUP_KEEP and CODEX_BACKUP_ROOT, or skip with --no-backup.

Restore is two commands:

rsync -a --exclude MANIFEST.txt --exclude SHA256SUMS ~/.codex-backups/codex-config-<timestamp>/ ~/.codex/
codex doctor   # expect: config.toml parse: ok

Two safety details worth knowing. Fugu’s provider settings go into config.toml inside managed # >>> fugu:... >>> markers, so a re-deploy replaces only that block and leaves the rest of your config untouched. And after every edit the installer re-parses the file with codex doctor — if it no longer parses, the change is rolled back automatically.

Installer flags reference

Flag	What it does
(none)	Install and pin the Codex CLI, then deploy the Fugu config
--set-key	Re-prompt for and store the Sakana API key, no redeploy
--remove-config	Cleanly undo the deployed config
--pinned-version X.Y.Z	Pin a specific Codex version instead of the default
--force	Deploy even if the installed Codex version doesn’t match the target
--dry-run	Show what would happen and change nothing
-y, --yes	Assume yes, for non-interactive use

--dry-run deserves a highlight: it prints everything the installer would do without touching your system — run it first if you’re cautious about curl-pipe installs.

Quick troubleshooting

The three most common snags: a failed partial install (fix: rm -rf ~/.fugu and re-run the one-liner — a plain re-run reuses the broken clone); Codex not found or the wrong version running (the installer warns when its Codex isn’t on PATH or another install shadows the pinned one — follow the printed PATH fix); and authentication errors (rotate the key with codex-fugu --set-key). The full failure catalog, including where every file lives, is in the troubleshooting guide.

Related: Fugu in Claude Code, the Windows setup, install troubleshooting, and the full API guide. Want to feel the models before committing to a setup? The browser playground takes two minutes.