FAQ

Can't find your answer? Ask in the Discord. It's usually the fastest way to get help.

Does it run on Windows?Link to this section

Yes. Empryo runs natively on Windows 10 (1809 or later) and Windows 11 on x64. You can use the setup installer or the portable ZIP from the download page. Saved keys are encrypted with Windows DPAPI. WSL also works if you prefer Linux. See Windows notes for the few features that differ.

Can the desktop app open a repo that lives in WSL?Link to this section

Yes. Open the folder through \\wsl.localhost\<distro>\… or \\wsl$\<distro>\… (File Explorer lists it under Linux). Empryo then runs inside that distro, so git, language servers, the Genome and every command use the Linux tools and files. Settings and keys come from the distro's ~/.empryo, the same ones the terminal app uses there. The terminal panel opens a shell in the distro, and dev servers you start from the app run there too.

The first time you open a WSL folder, Empryo installs its engine into the distro, which takes about a second. A folder under /mnt/c opens with the Windows engine instead, because Windows files are faster from Windows. Running inside the distro needs WSL 2 on x86_64 with glibc, such as Ubuntu or Debian. A WSL 1, ARM or musl (Alpine) distro still opens, with the Windows engine, and Empryo tells you why.

Each distro has its own sign-ins and keys, separate from Windows. The first time, sign in from the app as usual: the sign-in is saved in that distro. A model server running on Windows (Ollama, LM Studio) is not at localhost from inside WSL unless you turn on mirrored networking; otherwise point the provider at the Windows host address.

Do I need Neovim?Link to this section

No. Neovim powers an optional editor panel. Everything else works from the chat alone. If you want the panel, run /setup to check and install prerequisites, or install Neovim with empryo addon install neovim.

Is there a GUI, or is it terminal-only?Link to this section

Both. The desktop app gives you tabs, a visual map of your codebase, and a built-in editor and terminals in one window. The command-line install gives you the terminal UI and a --headless mode for scripts and CI. All three share the same agent, settings, and sessions.

Can I import sessions from Claude Code, Codex, or OpenCode?Link to this section

Yes. Run /import. It finds sessions from those tools on your machine, shows you what it found, and copies them into Empryo. Each session is imported separately, so one bad file doesn't stop the rest.

Do I need an API key?Link to this section

No. You have three options.

Sign in with an account. Type /login and pick an account, such as a Claude or ChatGPT subscription, GitHub Copilot, or LLM Gateway. Empryo opens your browser and saves the sign-in for you. LLM Gateway gives you many models behind one account, paid with credits (/login llmgateway) or a DevPass subscription (/login llmgateway-devpass).

Use a key you already have. Any supported provider works:

empryo --set-key anthropic sk-ant-...

Run a local model. Install Ollama or LM Studio and start it. Empryo detects both. Local runs cost nothing in API fees.

ollama pull llama3.3

How much does it cost to run?Link to this section

Empryo itself is free. You pay your model provider for what you use, or nothing if you run a local model. Empryo shows the running cost in US dollars as you work, including a breakdown per model.

Costs depend on the model, the size of your project, and how you work. To save money, use the task router to send exploration to a cheaper model and keep a stronger model for writing code.

Which model should I pick?Link to this section

Start with a model you already have access to. A mid-range model is a good default for everyday coding. A fast, cheap model works well for exploring code, and a top-tier model is worth it for hard bugs. Local models (Llama, Qwen, DeepSeek and others) keep everything on your machine.

You can mix models with /router. See the task router recipe.

Does it work without internet?Link to this section

Yes, if you use a local model through Ollama or LM Studio. The codebase map, language servers, and code parsing all run on your machine anyway.

How does Empryo edit code?Link to this section

It picks the right edit tool for the job:

1. Structure-aware edits for TypeScript and JavaScript. It changes a function, class, or method by name instead of matching text.
2. Batch edits that apply several changes to one file at once, or not at all.
3. Single text edits anchored to specific lines, for any file type.
4. Language-server refactors such as renaming a symbol across the project, moving a symbol, or extracting a function, where your language server supports them.

You don't choose. The agent does.

Is my code uploaded anywhere?Link to this section

Only what gets sent to the model provider you chose, as with any AI coding tool. Empryo doesn't upload your code to its own servers.

You can block files from the agent completely with /privacy. Common secret files such as .env, .pem, id_rsa, .npmrc, and .netrc are blocked by default.

Can I use it for work?Link to this section

Yes. You can use Empryo for personal projects and internal business work, including company development, paid client work, and headless CI/CD. You can sell the software and other work products you create with it. Using Empryo gives its owner no ownership of, or license to, your projects, inputs, or outputs. You owe no royalties, revenue share, source disclosure, or Empryo attribution for what you create. Existing rights in any third-party material still apply. You bring your own model access, so provider charges are separate.

Commercializing Empryo itself is different: selling it, offering cloud or managed Empryo to customers, or wrapping, embedding, or bundling its functionality in a commercial product or service requires the owner's explicit prior written permission in a separate commercial license. This also applies when Empryo is a free feature of a paid offering. Contact empryo@proxysoul.com.

Empryo v3 is proprietary, not open source. The separate public SoulForge v2/core/engine code keeps its own license; earlier grants are not revoked. The Empryo license defines the terms for copies distributed with it.

Which languages does code intelligence cover?Link to this section

Empryo parses structure, symbols, and imports for dozens of languages, including TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, Lua, Elixir, Dart, Zig, and Bash, plus formats such as JSON, YAML, TOML, CSS, and HTML. Other files, such as Markdown, SQL, and Dockerfiles, are still found and searchable, just not parsed in depth.

Language-server features depend on which servers you have installed. Structure-aware edits are for TypeScript and JavaScript only.

Can I install language servers from Empryo?Link to this section

Yes. Run /lsp install to browse and install servers from the Mason registry. Run /lsp status to see which servers are running.

How do sessions work?Link to this section

Every conversation is saved automatically under ~/.empryo/sessions/. In the terminal UI, open /session history to find and resume one. In headless mode, use empryo --headless --session <id> "your prompt". Checkpoints let you roll back changes the agent made in earlier turns.

Can I run it over SSH?Link to this section

Yes. The terminal UI runs in any terminal, including over SSH and inside tmux.

Can I work in several tabs?Link to this section

Yes. Each tab has its own session, model, and checkpoint history. Tabs know about each other, so two agents don't edit the same file at once. See tabs.

How do themes work?Link to this section

Run /theme to open a picker with live preview. Empryo ships with many built-in themes, and you can add your own. See themes.

Can Empryo explain and configure itself?Link to this section

Yes. Ask how something works, such as "what is the Genome?" or "why did it compact?", and it reads its current documentation instead of guessing. Ask it to change something, such as "turn thinking on" or "connect this MCP server", and it writes the setting the same way the Settings panel does, so most changes apply without a restart.

It saves the change where you asked. A general preference goes in ~/.empryo/config.json. A change "for this project" goes in .empryo/config.json. It tells you the old and new value and where it saved it. If a setting needs a restart, it says so.

There are two exceptions. It won't handle credentials for you (use /login, /keys, or empryo --set-key), and it asks before anything risky, such as installing software, upgrading, or changing project trust. See configuration.

How do I get help?Link to this section

• Troubleshooting covers common problems.
• /diagnose inside Empryo checks language servers, code parsing, and indexing.
• /status shows a system status dashboard.
• GitHub issues for bugs and requests.