Docs

<!-- generated by iii-skill-render. DO NOT EDIT (changes here are overwritten on the next render). Edit docs/next/install.mdx. -->

# Install


{/* TODO (community feedback): Add a direct binary-download path alongside the curl|sh installer so users who do not want to verify a remote script with a bot, or are on Windows, have an alternative. Link to the GitHub Releases page for the engine and include PATH setup instructions per OS (especially Windows). */}

## Start a project

The recipe below installs the engine and starts a project. Once started you can explore the project
via http://127.0.0.1:3113.

Select **llm** to let the installer set up the harness for you, or select **no llm**.

<div className="iii-qs" role="group" aria-label="quickstart recipe">
  <input className="iii-qs-radio" type="radio" name="iii-qs" id="qs-llm" defaultChecked />
  <input className="iii-qs-radio" type="radio" name="iii-qs" id="qs-none" />

<div className="iii-qs-head">
  <div className="iii-qs-picker">
    <label className="iii-qs-pill" htmlFor="qs-llm">
      llm
    </label>
    <label className="iii-qs-pill" htmlFor="qs-none">
      no llm
    </label>
  </div>
</div>

  <div className="iii-qs-body">
    <div className="iii-qs-comment"># Install iii</div>
      <div className="iii-qs-cmd">
        <span className="iii-qs-prompt">$</span>
        <span>curl -fsSL https://install.iii.dev/iii/main/install.sh | sh</span>
      </div>
    <div className="iii-qs-gap" aria-hidden="true" />
    <div className="iii-qs-slot" data-qs="llm">
      {/* prettier-ignore */}
      <div className="iii-qs-comment">{`# You'll be prompted to try out the harness. Press "y" at the prompt.`}</div>
      <div className="iii-qs-gap" aria-hidden="true" />
      <div className="iii-qs-comment"># Open your browser to http://127.0.0.1:3113</div>
    </div>
    <div className="iii-qs-slot" data-qs="none">
      {/* prettier-ignore */}
      <div className="iii-qs-comment">{`# You'll be prompted to try out the harness. Press "n" at the prompt.`}</div>
      <div className="iii-qs-gap" aria-hidden="true" />
      <div className="iii-qs-comment"># Create a project</div>
      <div className="iii-qs-cmd">
        <span className="iii-qs-prompt">$</span>
        <span>iii project init my-app && cd my-app</span>
      </div>
      <div className="iii-qs-gap" aria-hidden="true" />
      <div className="iii-qs-comment"># Start your project</div>
      <div className="iii-qs-cmd">
        <span className="iii-qs-prompt">$</span>
        <span>{'iii compose --up'}</span>
      </div>
      <div className="iii-qs-gap" aria-hidden="true" />
      <div className="iii-qs-comment"># Open your browser to http://127.0.0.1:3113</div>
      <div className="iii-qs-gap" aria-hidden="true" />
      {/* prettier-ignore */}
      <div className="iii-qs-comment"># You can also check out <a href="./quickstart">iii.dev/docs/quickstart</a> to learn more about iii</div>
    </div>
  </div>
</div>

The panel above is one recipe with an llm and a no-llm form. Plain form: install iii with `curl -fsSL https://install.iii.dev/iii/main/install.sh | sh`. The installer then prompts you to try the harness. Press `y` and the installer scaffolds and starts the harness for you. Press `n` for no llm, then run `iii project init my-app && cd my-app` and start it with `iii compose --up`. Both forms end at http://127.0.0.1:3113 in your browser.

{/* TODO: re-enable the "## 3. Install the VS Code Extension (Optional)" section once the iii-lsp extension is more thoroughly tested across VS Code, Cursor, Windsurf, and VSCodium. The Frame demo also needs `/images/lsp.mp4` to be captured and committed before the section is re-added. Before re-enabling, move the capability description (what completions/hover/diagnostics the extension provides) to an overview/explanation page for the extension and link to it from a single-sentence description here. ## 3. Install the VS Code Extension (Optional) The iii Language Server extension adds iii-aware editor support. See the extension overview for details. <Frame> <video autoPlay loop muted playsInline src="/images/lsp.mp4" alt="iii Language Server extension" /> </Frame> Open the Extensions panel and search for `iii-lsp`, or install from the terminal: <Tabs> <Tab title="VS Code"> code --install-extension iii-hq.iii-lsp </Tab> <Tab title="Cursor"> cursor --install-extension iii-hq.iii-lsp </Tab> <Tab title="Windsurf"> windsurf --install-extension iii-hq.iii-lsp </Tab> <Tab title="VSCodium"> codium --install-extension iii-hq.iii-lsp </Tab> </Tabs> */}

{/* TODO: re-add a "## 4. Add Agent Skills (Optional)" section with `npx skills add iii-hq/iii/skills` once the iii skills worker ships (owned by Sergio). */}

## Installer options

The installer takes its options after `sh -s --`. To see them all:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --help
```

### Run the setup against an installed engine

`--skip-bin-download` skips the download and the install, and runs the setup offer against the iii
that is on the machine already. Use it to repeat the setup, or when you build the engine yourself:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --skip-bin-download --start-with database
```

### Install a pre-release

Use `--next` for the latest `next` pre-release, or `--rc` for the latest release candidate:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --rc
```

To install one exact version, give the version as the last argument:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- 0.23.1
```

### Install without questions

The installer asks nothing when no terminal is attached. A `docker build` step, a CI job, and a
plain `curl ... | sh` in a script are already non-interactive, and they do the install and then
print the setup command.

`--non-interactive` makes that behavior explicit, and keeps it when a terminal is attached. The
effect is the same as an answer of `n` at the prompt: the installer does the install, does not run
the setup, and prints the setup command. Use it when a terminal is attached but you want the install
only, for example `docker run -it`, `docker compose run`, or a wrapper that gives the command a
terminal:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --non-interactive
```

A non-empty `III_NON_INTERACTIVE` does the same:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | III_NON_INTERACTIVE=1 sh
```

### Start the harness with your workers

`--start-with` takes a comma-separated worker list. The setup offer at the end of the install
scaffolds a harness project named after the first worker in the list, starts it, and adds every
worker in the list with `compose::add`:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --start-with database,storage
```

This example creates `iii-database`, starts it, then adds the `database` and `storage` workers. Each
added worker reads the project `.env` file. Put `onboarding` in the list to also get the guided tour
that the plain install offers.

### Ask for more environment variables

`--need-envs` takes a comma-separated list of variable names. The setup asks for each one after the
inference provider key, writes the answers to the project `.env` file, and puts them in the
environment of the `iii compose --up` process. Use it for a worker that needs its own key:

```bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- --start-with worker1 --need-envs WORKER_API_KEY
```

`--need-envs` is only valid together with `--start-with`.

<Warning>
  Every worker in the `--start-with` list receives the full project `.env` file. Use these flags
  with workers you trust.
</Warning>

### Control the install with environment variables

| Variable              | Effect                                                                              |
| --------------------- | ----------------------------------------------------------------------------------- |
| `VERSION`             | Engine version to install, for example `0.23.1`.                                    |
| `BIN_DIR`             | Directory for the engine binary. Defaults to `$PREFIX/bin`, or `$HOME/.local/bin`.  |
| `PREFIX`              | Install prefix. Defaults to `$HOME/.local`.                                         |
| `TARGET`              | Target triple to install, for example `aarch64-unknown-linux-gnu`.                  |
| `III_USE_GLIBC`       | Any non-empty value selects the glibc build on Linux x86_64. The default is musl.   |
| `GITHUB_TOKEN`        | Authenticates the GitHub API calls and raises the rate limit from 60/hr to 5000/hr. |
| `III_NON_INTERACTIVE` | Any non-empty value does the same as `--non-interactive`.                           |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="./quickstart" icon="terminal">
    Follow the Quickstart and explore a live iii application.
  </Card>
  <Card title="Use iii" href="./using-iii" icon="table-layout">
    Learn how to use iii in production.
  </Card>
</CardGroup>