Atuin AI Proxy Review 2026: Keep Atuin's ? Assistant, Drop the Hosted Backend

Atuin has quietly become one of those tools people refuse to work without. It replaces your shell’s Ctrl+R with a fast, searchable, end-to-end encrypted history that follows you between machines. Since v18.13 it also ships an AI assistant: press ? on an empty prompt, describe what you want in English, and get a command back that you can run with Enter or edit with Tab.

The assistant is good precisely because it is nosy. It can pull in your shell history, exit codes, working directory, and even command output as debugging context — which is exactly why some people won’t turn it on. Atuin AI requires an Atuin Hub account by design, and that context has to leave your machine to be useful. Atuin’s own documentation says you may self-host the AI backend instead, but it doesn’t hand you a server to do it with.

Atuin AI Proxy is a third-party attempt to fill that gap. It is roughly one weekend of carefully written Python that pretends to be Atuin’s Hub AI endpoint and forwards your prompts wherever you tell it to.

What Atuin AI Proxy Does

Atuin’s client expects a very specific thing on the other end of its [ai].endpoint setting: a POST /api/cli/chat route that returns a text/event-stream and sets an x-atuin-ai-session-id header. The proxy implements that contract, then translates between Atuin’s event vocabulary and whatever your upstream provider actually speaks.

That translation layer is the real work. Upstream response.output_text.delta events and Chat Completions choices[].delta.content chunks both become Atuin text events. Completed function_call items and Chat Completions tool_calls both become tool_call. A response.completed or a Chat Completions [DONE] becomes done, and upstream failures become error. Client-side tools are only advertised to the model when Atuin says it supports them, with one exception: suggest_command is always exposed, because that’s the whole point — the model needs a way to hand you back a command.

Configuration is three lines on the Atuin side:

[ai]
enabled = true
endpoint = "http://localhost:8000"
api_token = "change-me"

Set api_token to match the proxy’s ATUIN_PROXY_TOKEN and you have bearer auth. Leave ATUIN_PROXY_TOKEN unset and the proxy accepts local requests unauthenticated, which is convenient for a laptop and a bad idea on anything with a network interface you don’t control.

Use Cases

Keeping shell context off a third-party server. This is the primary reason to bother. If you work on client infrastructure, in a regulated environment, or just have a strong opinion about where your command history goes, the proxy lets you keep Atuin’s ergonomics while terminating the AI path inside your own perimeter.

Reusing a Codex subscription you already pay for. The codex-token and codex-oauth backends are the most interesting part of this project. If you already have a Codex plan, you can point Atuin’s assistant at it rather than opening a second metered API relationship. Device login is one command: docker compose run --rm atuin-ai-proxy atuin-ai-proxy auth login --device-code. You can also just mount an existing Codex CLI auth.json at /data/codex/auth.json.

Pinning a specific model. Atuin decides what model backs its hosted assistant. Through the proxy, you set MODEL yourself and can point at a local Ollama-style endpoint, a cheaper hosted model, or a frontier model — anything that speaks OpenAI’s protocol.

Debugging why the assistant is misbehaving. Because everything routes through a process you control, you can turn logging up and actually watch what Atuin sends and what comes back. That’s not possible against a hosted black box.

Key Features

Three backends, one endpoint

BACKEND=openai targets any OpenAI-compatible API. BACKEND=codex-token uses a Codex access or personal access token plus an account ID. BACKEND=codex-oauth reads a Codex OAuth auth.json. The OPENAI_API switch accepts auto, responses, or chat_completions; the default auto tries Chat Completions first and falls back to Responses when Chat Completions gets rejected as unsupported. The Codex backends only support the Responses API, and if you misconfigure OPENAI_API=chat_completions against them the proxy logs a startup warning and quietly does the right thing instead of failing.

Zero runtime dependencies

The README is blunt about it: the implementation uses only the Python standard library at runtime. For a network-facing service that sits in the path of your shell history, that is a meaningful security and maintenance property. There is no dependency tree to audit, pin, or wake up to a CVE in. Tests run with python3 -m unittest discover -s tests.

Traceability built in, with an honest warning

Every HTTP response and stream error carries a request id. When Atuin reports a vague SSE request failed (...), you copy the request_id out of the JSON body and grep the proxy log. Logging goes INFO, WARNING, DEBUG, and then TRACE, which dumps sanitized and byte-bounded request, backend, and SSE payload excerpts via TRACE_PAYLOAD_BYTES. The README explicitly warns that TRACE output can still include shell history, prompts, paths and command output, and tells you to use it only while diagnosing a problem. That disclosure is the right instinct and more than many larger projects manage.

A documented failure table

Rather than making you guess, the README maps concrete errors to causes: 400 missing_model means set MODEL, 401 unauthorized means your api_token doesn’t match ATUIN_PROXY_TOKEN, 502 auth_error means backend credentials are missing or invalid, 502 upstream_http_error includes a sanitized upstream excerpt, and 504 upstream_timeout means the backend blew past REQUEST_TIMEOUT_SECONDS.

Pricing

The proxy is free. There is no account, no tier, and no telemetry.

The honest complication is that the economics currently argue against it. Atuin AI is free while in testing, so today you would be trading a free hosted service for a paid API relationship, purchased with your own setup time. Atuin’s paid Personal Pro sync plan runs about $2/month or $20/year, and that’s for history sync, not the assistant.

So the value proposition right now is privacy and model choice, not savings. That flips the moment Atuin AI leaves testing and picks up a price tag — at which point a proxy pointed at a subscription you already own becomes straightforwardly cheaper.

One caveat that matters more than the price: there is no LICENSE file in the repository. Source you can read is not the same as source you have been granted rights to use, and by default that means all rights reserved. For personal tinkering nobody will care. If you have a licensing policy at work, this is a blocker until the maintainer adds one.

Common Questions

Does this let me use Atuin AI without an Atuin account? For the AI path, yes — the proxy is the backend, so there is no Hub call in that flow. Atuin’s history sync is a separate feature with its own account requirement, and self-hosting the sync server is officially supported.

Will it break when Atuin updates? Possibly. POST /api/cli/chat is an internal contract, not a published stable API. The proxy tracks it by observation, so an upstream change can break compatibility with no warning. Combined with no commits since 2026-07-10, treat that as real risk.

Is it production-ready? For a single developer’s laptop, it’s fine — it’s small, tested, and dependency-free. For a team, no. There is no multi-user support, no quota accounting, no per-user keys, and no license. If you need shared team infrastructure, a general gateway like LiteLLM is the better foundation, though you’d have to bridge Atuin’s contract yourself.

Verdict

Atuin AI Proxy is a good piece of small software solving a genuinely narrow problem. The stdlib-only runtime, the documented error table, the request-id tracing, and the frank warning about what TRACE logs can leak all suggest someone who has operated software before, not someone shipping a demo. The Codex-subscription backends are a clever touch that a bigger project probably wouldn’t have bothered with.

But it is a 3-star, 0-fork repository with no commits since July, one maintainer, and no license file. Nothing about it is broken; there is just very little community insulation if the author moves on or Atuin changes its endpoint.

Use it if you already run Atuin, you specifically want the ? assistant without shell context leaving your machine, or you want to route it at a Codex plan you’re already paying for. It will take you about ten minutes to stand up.

Skip it if you’re happy with Atuin AI as shipped — it’s free right now, and this adds moving parts for benefits you may not need. Also skip it if your organisation requires a clear license, at least until one appears in the repo.

A useful, well-mannered little tool for a specific kind of person. Just go in knowing you are adopting a weekend project, not a product.