Codex Desktop

Install and prepare a practice folder

These instructions were checked against official documentation on 2026-09-25. This is a setup and acceptance guide, not a new live-model acceptance result. You can use file assistants for marketing briefs, sales notes and operations checklists without writing software.

1. Download the desktop application for your operating system from the official page, install it and open Settings. Record the installed version. Keep your existing login and settings; back up config.toml before changing provider configuration.
2. Create a practice folder containing a short fictional notes.md file. Open that folder as a project. Allow only this folder initially; do not grant access to your whole home directory for a first exercise.

• Official Codex download
• Official provider configuration

Confirm the service and model

Get a Gateway /v1 address, a key and an allowed Responses-capable model alias from Albatross. In your user-level ~/.codex/config.toml, merge the Provider example below. Do not put model_provider or model_providers only in a project-level config: those provider fields are user-level settings. Replace <ALBATROSS_MODEL> with the exact permitted alias.

env_key names an environment variable, not the credential itself. The desktop process must receive the variable named by env_key through your supported local launch setup: ALBATROSS_API_KEY for text-only configuration, or OPENAI_API_KEY for the shared ImageGen key configuration. ImageGen also needs OPENAI_BASE_URL in Desktop and its tool subprocesses; follow the matching environment scheme below. Exporting it in an unrelated terminal does not prove that a Dock-launched app sees it. Restart the app after setup and verify the selected provider before sending a request. This environment handoff has not been validated here.

Configuration

Merge the example below into your user-level ~/.codex/config.toml; back up and preserve existing settings. Codex Desktop uses the same model_provider, base_url, env_key, wire_api, and requires_openai_auth fields as Codex CLI. Save the file and fully quit and restart Desktop to load it. Verify the provider and model before sending a request.

model = "<ALBATROSS_MODEL>"
model_provider = "albatross"

[model_providers.albatross]
name = "Albatross"
base_url = "https://staging-gateway.bulakua.com/v1"
env_key = "ALBATROSS_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Environment handoff

Desktop may not inherit variables exported in an unrelated terminal. Verify the environment handoff for your installed build and operating system, then choose one credential scheme below.

For text-only setup, use env_key = "ALBATROSS_API_KEY" in ~/.codex/config.toml and provide ALBATROSS_API_KEY. To share one key with ImageGen, replace that field with env_key = "OPENAI_API_KEY" and provide OPENAI_API_KEY plus OPENAI_BASE_URL to Desktop and its tool subprocesses. OPENAI_BASE_URL must match the provider base_url, including /v1. The two file examples are alternatives; use the ImageGen example when following the image guide.

Only if the installed build explicitly supports ~/.codex/.env, save the chosen file contents there and run the separate chmod command in a macOS/Linux terminal; otherwise supply the chosen variables through the build's supported launch setup. Do not set experimental_bearer_token at the same time. Fully quit and restart Desktop after changes, then verify the provider and model.

ALBATROSS_API_KEY=<ALBATROSS_API_KEY>

OPENAI_API_KEY=<ALBATROSS_API_KEY>
OPENAI_BASE_URL=https://staging-gateway.bulakua.com/v1

chmod 600 ~/.codex/.env

Required manual acceptance

• Provider and model selection
• Non-streaming and streaming text
• Tool calls and local permission prompts
• Read and modify a disposable file
• Cancellation and error display
• Usage record correlation using the returned request ID

Support boundary

• ImageGen configuration and limits

Switch models in Desktop

Desktop reuses the provider, env_key and key from ~/.codex/config.toml. Set one default model, then choose another exact alias in the Desktop model picker. Check model_catalog_json and restart if a custom alias is missing.

Work example: turn meeting notes into a follow-up

1. Put fictional notes in notes.md: a bookstore needs a Saturday reading-event invitation; the venue is not confirmed. Start a new task in the practice project (Desktop) or run claude in that folder (Claude Code). Ask for a one-sentence greeting first.
2. Ask: Read notes.md, summarize confirmed facts and missing information, and propose a follow-up checklist. Do not modify any file yet. Review the reported file read and compare the summary with the original.
3. Then ask: Write the approved checklist to follow-up.md in this folder, leaving notes.md unchanged. Review any write permission prompt, allow only the intended action, then open follow-up.md to check the saved result.
4. Success means a completed reply, a real readable output file and matching Albatross Usage, not only a promise to write a file. These are acceptance steps you must verify on your installed version; they were not executed in this round.

Daily use, automation and troubleshooting

• Continue the same task when revising the same files; start a new task for a separate assignment. Inspect changes before using or sharing them. Keep backups before bulk file operations.
• Tools execute on your computer or the client's selected environment. Reading files may send their content to the configured model. Grant only the needed folder and commands; review a proposed command if you do not understand it.
• For repeated work, first validate a single manual run and its output. Scheduled automation, plugins, network access and external publishing need separate client setup and authorization; this guide does not certify them.
• If a key is not found, check the launch environment; if a model is denied, check the exact alias and key permission. If a tool fails, inspect its actual output and local permission before blaming the Gateway. After cancellation, inspect partial files before resuming.
• Each planning or tool-continuation model request may be billed. Client subscription fees and estimates are separate from Albatross customer charges. For help provide version, model, time and request ID, never the key or private files.

• Account and costs
• Troubleshooting