OSA

How the engine and terminal work together

OSA, the Optimal System Agent, is two programs that cooperate on your machine. The engine is an Elixir and OTP application that acts as the brain: it runs the agent loop, the tools, the language model providers, memory, permissions, and persistence. Because it runs on the BEAM virtual machine, thousands of lightweight processes such as turns, sub agents, hooks, and streams run concurrently and supervise each other, so a single failure does not take the whole agent down. The interface is a Rust terminal user interface built on ratatui, and it is what you see and type into: the composer, the streaming message view, the dialogs, and the agent tree. The two halves talk over a small HTTP and server sent events API bound to 127.0.0.1 on port 9089 by default. The terminal never reaches the internet directly; it only speaks to your local engine, and the engine is the only part that talks to model providers. The README states that nothing leaves your machine unless a tool you approved makes it happen. The single osa command ties them together. The first launch starts the engine as a warm background daemon and attaches the terminal to it, and that daemon outlives the terminal so every later osa attaches instantly with no cold start. It idles down when unused and restarts itself when a newer version is installed on disk.

Installing and the first run setup

OSA installs with one command. On macOS or Linux you paste a curl piped install script from the project's scripts directory and then run osa. On Windows you run the install script from PowerShell and then run osa. The README stresses that no Elixir, Erlang, or Rust is required, because the installer detects your OS and CPU, downloads a prebuilt release from GitHub that bundles its own runtime plus a prebuilt Rust terminal, verifies its checksum, and unpacks everything under ~/.osa or the Windows equivalent, then puts the osa command on your PATH. Prebuilt targets are linux x64, macOS arm64, and windows x64, and you can pin a release with an environment variable. The first run drops you into a short setup wizard where you pick a provider, paste a key, or take the local Ollama default. The recommended path is Ollama Cloud with the glm-5.2:cloud model, which needs no GPU and no large downloads and gives a large context window. The README also lists other install routes: running bin/install from a cloned repo, building from source with an install-source script on any platform, or running docker compose up. Configuration lives in ~/.osa/.env, generated by the wizard, and anything already exported in your shell overrides that file, so a one off model override is easy.

Permission modes, workspace trust, and session commands

By default OSA asks before it touches anything consequential, and the README describes several permission modes. Ask is the default and approves each edit and command as it comes. Auto edit runs file edits automatically while commands still prompt. Plan proposes a plan and waits, writing nothing until you approve. Overdrive is full auto with no prompts. Auto is a safety guardian mode that classifies each call and only stops for risky ones. Shift and Tab cycles through ask, auto edit, plan, and overdrive even mid turn, and you can seed a mode at launch with a flag or go straight to full auto with osa overdrive. Workspace trust is another guard. A directory you have never used OSA in is untrusted, and its .osa/settings.json with its hooks, permission rules, and MCP settings is withheld rather than obeyed until you accept trust, so cloning a hostile repo cannot hand itself permissions. You run /trust to see the status and /trust accept to accept, and trust is remembered per directory. Session commands round out daily use: osa continue resumes the newest session in a folder, osa resume takes an id or opens a picker, osa setup re runs the wizard, osa update updates in place, osa doctor runs health checks, and osa stop stops the daemon. The id accepts a git short SHA style prefix, and bare osa resume opens a picker rather than guessing.

Editorial conclusion

OSA is an Elixir and OTP agent under the Apache 2.0 license that you install with a single curl or irm command, and it runs a local engine as a warm background daemon on port 9089 while the Rust terminal attaches to it.