> ## 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

> Install the SDK, connect your account, and configure your coding agent.

Run this command in a macOS or Linux terminal, or in WSL on Windows:

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

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](#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:

```sh theme={null}
lithosbox configure
lithosbox check
```

Activate the installed commands first, as described below.

## Use the installed SDK

Copy the activation command printed at the end of installation. With the default
location in sh, Bash, or Zsh, it is:

```sh theme={null}
. "${XDG_DATA_HOME:-$HOME/.local/share}/lithosbox/env.sh"
```

Run that activation command in each new terminal where you want to use LithosBox.
Fish users receive a corresponding `source …/env.fish` command.

Check your installation and run an SDK script:

```sh theme={null}
lithosbox --version
lithosbox python hello.py
```

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:

```sh theme={null}
lithosbox python -m pip install PACKAGE
```

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.

## 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:

```sh theme={null}
curl -fsSL https://console.sandbox.lithosai.cloud/install.sh | sh -s -- --skills all
```

To install skills for a specific project:

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

| 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 installation includes `runtime.md`, which tells the agent how to run the
SDK on your computer. Rerun setup on another computer even if the project already
contains skill files. See [Coding agents](/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:

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

Without interactive prompts, installation does not save credentials, install
skills, or create a sandbox unless you request those actions:

| Option          | Purpose                                         |
| --------------- | ----------------------------------------------- |
| `--skills all`  | Install all supported agent skills.             |
| `--save-token`  | Save a key supplied through `LITHOSBOX_TOKEN`.  |
| `--check`       | Run the sandbox check using your credentials.   |
| `--mcp`         | Include the dependencies for sandbox MCP tools. |
| `--prefix DIR`  | Choose where to install LithosBox.              |
| `--api-url URL` | Connect to another deployment.                  |

Provide credentials through your automation runner's secret environment. API keys
are not accepted as command-line arguments. For all installer options, run:

```sh theme={null}
curl -fsSL https://console.sandbox.lithosai.cloud/install.sh | sh -s -- --help
```

## Other ways to run the installer

With wget:

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

To inspect the script first, download it and open it in a text editor:

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

Then run the downloaded file:

```sh theme={null}
sh lithosbox-install.sh
```

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 to update. 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.

## Troubleshooting

| Problem                                | What to do                                                                        |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| `lithosbox: command not found`         | Run the printed activation command, or use the absolute `bin/lithosbox` path.     |
| Your script cannot import `lithosbox`  | Run it with `lithosbox python your_script.py`.                                    |
| Credentials are missing or rejected    | Run `lithosbox configure` with a key from the correct organization.               |
| Installation could not download a file | Check your connection and proxy settings, then rerun the installer.               |
| The sandbox check failed               | Read the error and inspect the printed sandbox ID in the console before retrying. |

A failed connection check does not undo the SDK installation. See
[Accounts and support](/launch#support) if the issue continues.