> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanovm.dev.lithosai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Install LithosBox

> One installer for the Python SDK, credentials, agent skills, and a first sandbox check.

Run the installer in a terminal on **macOS or Linux**, including **WSL** on Windows:

```sh theme={null}
curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh | sh
```

The installer detects your platform, finds or downloads Python 3.12, and installs the
published LithosBox SDK in a private virtual environment. It offers skills for
**Claude Code, Codex, and Cursor**, asks for an API key in a hidden prompt, and
offers a check that creates a sandbox, prints `42`, deletes it, and confirms deletion.

You can skip the key and sandbox check. Installation does not require an account;
using a sandbox requires an invited account and an API key from **Console → API Keys**.
Saving the key is a separate choice. Saved keys have owner-only permissions and
stay outside your project and shell profile.

## Requirements and standalone use

You need a POSIX shell, network access, and **curl, wget, or Python 3.10+ with HTTPS
support** to bootstrap the installer. An existing compatible `uv` installation also works. Python, pip,
venv support, Node.js, sudo, and agent CLIs are not prerequisites. Native Windows
terminals are not supported; run the script inside WSL.

To download and inspect the script before running it:

```sh theme={null}
curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh -o lithosbox-install.sh
sh lithosbox-install.sh
```

With wget:

```sh theme={null}
wget -qO- https://console.nanovm.dev.lithosai.cloud/install.sh | sh
```

The downloaded file is the complete installer. It still needs network access to
download Python when needed, the released SDK wheel, and its dependencies. Downloads
use HTTPS and your system's proxy settings. The installer uses a pinned release
of [uv](https://docs.astral.sh/uv/) for platform detection and Python installation.
If only Python is available, it uses PyPA's bootstrap in a temporary directory to
obtain uv; it does not install pip into your existing Python.

The installer's prompts read from your terminal, so they work with the one-line
command. The script waits for its complete bootstrap and end marker before it
starts installing.

## Use the installed SDK

Follow the activation command printed at the end. For the default location in
sh, Bash, or Zsh:

```sh theme={null}
. "${XDG_DATA_HOME:-$HOME/.local/share}/lithosbox/env.sh"
lithosbox --version
lithosbox python your_script.py
lithosbox check
```

Fish users receive a `source …/env.fish` command. The installer prints the exact
path when you choose a custom location. You can also run the printed absolute
`bin/lithosbox` path without activation; it selects the SDK's Python and loads a
saved API key. Use `lithosbox configure` to enter or replace a key later.

The installer leaves your system Python, existing project environment, dependency
files, and shell profiles intact. To add dependencies for your own script after
activation, use `lithosbox python -m pip install PACKAGE`. Keep a requirements file
for your application: a later installer run creates a fresh SDK environment.

## Agent skills

The interactive installer asks which agents to configure. Skills default to user
scope, so the agent can discover them across projects:

| Agent       | User skill directory         | Project skill directory    |
| ----------- | ---------------------------- | -------------------------- |
| Claude Code | `~/.claude/skills/lithosbox` | `.claude/skills/lithosbox` |
| Codex       | `~/.agents/skills/lithosbox` | `.agents/skills/lithosbox` |
| Cursor      | `~/.cursor/skills/lithosbox` | `.cursor/skills/lithosbox` |

Each skill includes the API guide and a `runtime.md` with this machine's exact
launcher path. Reload the agent's skills or start a new session, then ask it to
**use LithosBox**. A project installation is local to that machine: rerun the
installer on other machines instead of relying on a committed absolute path.

```sh theme={null}
curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh | sh -s -- --skills all
curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh | sh -s -- --skills claude,codex --scope project --project ./my-project
```

Existing changed skill files are backed up outside the agents' skill directories.
Linked skill files are preserved and reported so you can choose another scope.
See [For coding agents](/coding-agents) for usage and MCP configuration.

## Unattended installation

For Bash automation, enable `pipefail` so either a download or installation failure
returns a failing exit status:

```bash theme={null}
set -o pipefail
curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh | sh -s -- --non-interactive --skills none --skip-check
```

Noninteractive runs never prompt, save a key, install skills, or create a sandbox
unless you explicitly request the relevant action. `--skills all` selects skills,
`--save-token` saves a key supplied through `LITHOSBOX_TOKEN`, and `--check` runs
the sandbox check. Supply CI credentials through your runner's secret environment;
the installer accepts no key argument.

Use `--mcp` to include the optional sandbox MCP dependencies. Use `--prefix DIR`
to choose an installation directory, and `--api-url URL` for another deployment.
Run `curl -fsSL https://console.nanovm.dev.lithosai.cloud/install.sh | sh -s -- --help` for all options.

## Updates and failures

Rerun the installer to update. It validates the downloaded wheel and installs the
new environment before switching the launcher. A failed download or dependency
installation leaves the previous SDK environment usable. Previous environments
remain under `environments/`; skill backups remain under `backups/`.

If the sandbox check fails, read the error and inspect its printed sandbox ID in
the console before retrying. A failed check does not undo a successful SDK install.
Only `VERDICT: PASS` confirms that creation, execution, and cleanup all succeeded.

To remove the local installation, remove the exact installation directory printed
by the installer and any LithosBox skill directories you selected. This also
removes a key saved in that directory. It does not delete remote sandboxes.