Skip to main content
Run this command in a macOS or Linux terminal, or in WSL on Windows:
The installer sets up Python and the LithosBox SDK and walks you through optional agent skills, API-key setup, and a connection check. You do not need an existing Python installation or administrator access. You need an internet connection and curl for the command above. If you use wget, see Other ways to run the installer. Native Windows terminals are not supported; use WSL.

​
Connect your account

Create an API key in Console → API Keys, then enter it at the installer’s hidden prompt. You can choose whether to save the key for future use. Saved keys are readable only by your user account and are kept outside your project. Choose the sandbox check to verify your setup. It creates a sandbox, prints 42, deletes the sandbox, and confirms deletion. VERDICT: PASS means all steps succeeded. You can skip these steps during installation and run them later:
Activate the installed commands first, as described below.

​
Use the installed SDK

For everyday use, add LithosBox to PATH once and lithosbox works in every new terminal — no per-terminal activation. To use it in the current terminal right away instead, run the activation command printed at the end of installation. With the default location in sh, Bash, or Zsh, it is:
This is not a virtual environment: it only prepends one directory to PATH for this terminal. Fish users receive a corresponding source …/env.fish command. Check your installation and run an SDK script:
The introduction includes a complete hello.py example. Run SDK scripts with lithosbox python so they use the installed SDK and your saved configuration. You can also use the absolute bin/lithosbox path printed by the installer. To add a package your local SDK script needs:
This installs the package on your computer. To add a package inside a sandbox, run its package manager through sandbox.run(). Keep local dependencies in a requirements file so you can reinstall them after updating LithosBox.

​
Add LithosBox to PATH

The installer prints PATH instructions for your shell using the actual installation directory, including a custom --prefix. Follow those instructions to make lithosbox available in new terminals. The installer does not edit your shell files. For the default installation, use the instructions for your shell below.

​
Zsh

Add this line to ~/.zshrc, then open a new terminal:
If you use ZDOTDIR, edit $ZDOTDIR/.zshrc instead. You can also run the export line directly to use it in the current terminal.

​
Bash

Add this line to ~/.bashrc:
If your terminal starts a login shell, also add it to the first existing file among ~/.bash_profile, ~/.bash_login, and ~/.profile, unless that file already loads ~/.bashrc. If none exists, create ~/.bash_profile. Open a new terminal afterward.

​
Fish

Run this once to save the directory for current and future Fish terminals:
If you set XDG_DATA_HOME or chose a custom prefix, use the exact directory printed by the installer. For another shell, add that directory using its PATH syntax, or use the absolute bin/lithosbox launcher path. With PATH configured, run lithosbox --version to check it. Continue using lithosbox python your_script.py for SDK scripts; the launcher uses your installed SDK and loads any API key you chose to save.

​
Set up agent skills

Select Claude Code, Codex, or Cursor when the installer asks which agents to configure. Restart your agent or reload its skills, then ask it to use LithosBox. By default, skills are available across your projects. To select agents explicitly:
To install skills for a specific project:
Each installation includes runtime.md, which pins the absolute launcher path for THIS computer — that is the machine-specific file, and why setup must be rerun on another computer even when the project already contains skill files. The skill itself is generic: it tells the agent to read runtime.md when present and to fall back to the bundled setup.md (or this page) when it is missing, so an agent on a machine without a local installation can bootstrap one. See Coding agents for examples and MCP setup.

​
Unattended installation

Use --non-interactive in automation. In Bash, enable pipefail to report either a download failure or an installation failure:
Without interactive prompts, installation does not save credentials, install skills, or create a sandbox unless you request those actions: Provide credentials through your automation runner’s secret environment. API keys are not accepted as command-line arguments. For all installer options, run:

​
Other ways to run the installer

With wget:
To inspect the script first, download it and open it in a text editor:
Then run the downloaded file:
The downloaded installer still needs internet access. It can use curl, wget, Python 3.10+ with HTTPS support, or an existing compatible uv installation to complete setup. It leaves your system Python, shell profiles, and project environments unchanged.

​
Update or remove LithosBox

Rerun the installer and select your agents again to update the SDK and their skills. Restart your agent or reload its skills afterward. If the download or dependency installation fails, your previous SDK installation remains usable. Custom skill files are backed up under the installation directory before replacement; linked skill files are preserved and reported. To remove LithosBox, delete the installation directory printed during setup and any LithosBox skill directories you selected. This removes a key saved locally; it does not revoke the key or delete your sandboxes. Manage those in the console. Remove the PATH entry from your shell configuration if you added one.

​
Troubleshooting

A failed connection check does not undo the SDK installation. See Accounts and support if the issue continues.