---
name: im-setup
description: Get a machine ready to build in·manas agents, checking each step instead of assuming it. Installs the `im-cli` command-line tool from the public downloads host, confirms the `im-sdk` Python package index resolves, and verifies the toolchain an agent project needs — Python 3.11 or newer and `uv` — via `im-cli doctor`. Use when the user wants to "install im-cli", "set up the in-manas CLI", "get set up for CIU", asks why `im-cli` or `uv` is not found, or needs to know whether this machine can build an agent before scaffolding one. Works with no credential of any kind, since discovery and download are anonymous static files. Stops short of logging in, which needs the organisation's own Portal URL. For creating a project use im-create-agent; for bumping an existing one use im-update-agent.
---

# Get this machine ready to build an agent

Four things, in this order, each **checked rather than assumed**: put a working
`im-cli` on `PATH`, confirm the machine can resolve `im-sdk` from the public
index, confirm it has the Python and `uv` an agent project needs, and — once
there is an agent — confirm it has both kinds of grant.

They fail for different reasons and a project needs all of them. Skipping a
check does not save time; it moves the failure to the first `uv sync` or the
first LLM call, where the error names none of this.

**No credential is involved.** `https://downloads.mgt-platform.com` serves static
files anonymously: the release index, the archives, the PEP 503 index and the
wheels. If any step here asks you for a token, something is wrong: stop and say
so rather than looking for one.

**Never hard-code a version.** Read it from the index at run time. Any version in
a command you paste is stale at the next release.

---

## 1. Is it already installed?

```sh
im-cli --version
```

Prints a bare version (`1.1.0`) and exits `0` if it is there. If that works and
the user only wanted the CLI, skip to step 3. Reinstalling on top of a working
binary gains nothing.

`im-cli version` (no dashes) prints a JSON record with `version`, `commit` and
`date`, which is the one to parse.

## 2. Install

### macOS and Linux

```sh
curl -fsSL https://downloads.mgt-platform.com/install.sh | sh
```

It resolves the newest release that is neither a pre-release nor withdrawn,
picks the archive for this `uname -s`/`uname -m`, **verifies the release
signature against the key pinned in the script and the archive's SHA-256 against
that signed manifest before extracting**, and installs to `~/.local/bin`.

The key is inline in the installer rather than fetched from the host, so an
anchor served beside the artifacts cannot vouch for them. If verification fails
the script prints the fingerprint it pins; that string is published in the
ciu-next README and at `/docs/cli/getting-started` in the Portal, neither of
which this host serves. Report a mismatch, never work around it — and never
suggest `--no-verify-signature` to get past one. That flag exists only for a
machine with no `ssh-keygen` at all.

Options go after `-s --`, which is easy to get wrong through a pipe:

```sh
curl -fsSL https://downloads.mgt-platform.com/install.sh | sh -s -- --bin-dir /usr/local/bin
```

- `--bin-dir <path>`: install somewhere else (it uses `sudo` only if it must)
- `--version <x.y.z>`: pin a specific release
- `--verbose`: print each step, which is what to turn on before reporting a failure

If `~/.local/bin` is not on `PATH`, the installer says so and prints the line to
add. Do not silently edit the user's shell profile. Show them the line.

### Windows

There is no shell to pipe into. Read the index, take the `windows` archive, and
unpack it:

```powershell
$idx = Invoke-RestMethod https://downloads.mgt-platform.com/releases/cli/index.json
$rel = $idx.releases | Where-Object { -not $_.prerelease -and -not $_.withdrawn } | Select-Object -First 1
$asset = $rel.assets | Where-Object { $_.os -eq 'windows' -and $_.arch -eq 'amd64' }
Invoke-WebRequest $asset.url -OutFile $asset.name
(Get-FileHash $asset.name -Algorithm SHA256).Hash -eq $asset.sha256.ToUpper()   # must be True
Expand-Archive $asset.name -DestinationPath .
```

Only `windows_amd64` is published; there is no Windows ARM64 build. If
`sha256` comes back `null`, fall back to the release's `checksums.txt` asset; do
not skip the check.

### Confirm

```sh
im-cli --version && im-cli doctor
```

`doctor` prints JSON describing the local config and whether an API is
reachable. On a fresh machine it reports `"config_exists": false` and a note to
log in, which is the expected state here, not a failure.

## 3. Check `im-sdk` is reachable

The CLI and the SDK arrive by different routes. A working `im-cli` says nothing
about whether `uv` can resolve `im-sdk`, and that is what a project needs.

**Cheap check: does the index list anything?**

```sh
curl -fsS https://downloads.mgt-platform.com/simple/im-sdk/
```

It should return a PEP 503 page whose links end in `#sha256=<64 hex>`. No
fragment means nothing verifiable to install and the index is wrong; report that
rather than working around it.

**Real check: does it actually resolve and import?**

```sh
uv venv /tmp/im-sdk-check
uv pip install --python /tmp/im-sdk-check/bin/python \
  --extra-index-url https://downloads.mgt-platform.com/simple/ im-sdk
/tmp/im-sdk-check/bin/python -c "import im_sdk; print(im_sdk.__version__)"
```

That prints the installed version. The SDK reads it from its own distribution
metadata, so `0+unknown` means it is being imported from a source tree rather
than an installed distribution.

**`--extra-index-url` here is a throwaway-check convention, not project
configuration.** A real project pins the index explicitly so `uv` searches it for
`im-sdk` alone:

```toml
[[tool.uv.index]]
name = "in-manas"
url = "https://downloads.mgt-platform.com/simple/"
explicit = true

[tool.uv.sources]
im-sdk = { index = "in-manas" }
```

Without `explicit = true`, `uv` searches this index for *every* dependency in the
project, and a public package sharing a name with something published here
resolves from the wrong place. Do not copy the `--extra-index-url` form into a
`pyproject.toml`.

## 4. Check the toolchain an agent project needs

`im-cli` is a static binary and needs nothing. **An agent project needs Python
3.11 or newer and `uv`**, and neither arrives with the CLI. Ask the CLI:

```sh
im-cli doctor
```

It reports the CLI build, the config path, the active login if there is one, and
a `Python` and `uv` row. Where a tool is missing or too old, the output names the
command that fixes it.

**No `Python` or `uv` row at all** means the binary predates the check, not that
the tools are fine. Run `im-cli upgrade` and ask again — do not fall back to
checking by hand, because the point of asking the CLI is that one place owns the
answer and a second copy of the rules drifts from it. Step 2 installs the newest
release, so this only comes up on a machine that already had `im-cli` and skipped
that step.

The rows report **even when nobody is logged in**, which is the state a machine
is in while it is being set up.

Two things worth knowing before you act on them:

- **`uv` first, then Python.** The fix for a missing Python is `uv python install
  3.11`, so a machine missing both gets `uv` installed first. Doctor lists them
  in that order for that reason.
- **Never replace the system interpreter.** `uv python install` puts an
  interpreter where `uv` manages it. Changing what `python3` means system-wide
  breaks things that have nothing to do with this.

If `uv` installs but the shell still cannot find it, `~/.local/bin` is not on
`PATH` — reopen the shell, or add it. That accounts for most first-time failures
and is not a broken install.

## 5. Once there is an agent: check it has *both* kinds of grant

This one is per-agent, not per-machine, so it comes after `im-cli link`. It is
also the failure that looks least like one:

```sh
im-cli agent services
im-cli agent models
```

**An agent can have every service granted and no model aliases.** It then looks
fully provisioned — `services` lists `openai` as active — and dies on its first
`core.llm.call`, because model access is a separate grant that nothing on the
agent page implies. If `models` returns `[]`, the agent cannot call an LLM no
matter what `services` says.

There is nothing to fix from here: grants are issued in the Portal by an
organisation admin. Say which of the two is empty, because "the agent has no
access" sends someone to the wrong tab.

## 6. What this skill does not do

**Logging in.** `im-cli login --api-url <url>` needs the URL of the
organisation's own Portal. There is no public one, so it cannot be guessed. Ask
the user for it, or for whoever administers their Portal.

**Linking, pushing, running.** All three need an agent an administrator already
created in that Portal, plus the grants it carries. Hand off to
`im-create-agent` (new project), `im-update-agent` (existing project on an older
SDK), or the getting-started guide under `/docs/`.

**Issuing grants.** Step 5 tells you which grant is missing; only an organisation
admin can add it, in the Portal.

**Fixing anything server-side.** An organisation with no workspace, or a
workspace with no free runner container, is not something this skill can repair —
a push fails and the answer is with whoever administers the Portal. Say so plainly
rather than retrying.

---

## When a step fails

Each of these is a real first-run failure, and each has one answer:

| What you see | What it is |
|---|---|
| `im-cli: command not found` after a clean install | `~/.local/bin` is not on `PATH`. Reopen the shell |
| The installer refuses without `ssh-keygen` | Deliberate — it will not skip signature verification. Install `openssh-client` (Debian/Ubuntu) or `openssh-keygen` |
| macOS refuses to run the binary | Gatekeeper on an unsigned download. The user clears it themselves in System Settings; do not work around it |
| `uv` installs, shell still cannot find it | Same `PATH` story as the CLI |
| Doctor shows no `Python`/`uv` rows | The binary predates the check — `im-cli upgrade`, then ask again |
| `im-cli login` succeeds but nothing is authorised | The login replaced a previous one; there is one active login at a time. `im-cli whoami` shows which server |
| Registration is refused | The Portal is invitation-only. Someone with an admin account has to invite them |
| No network to the index | Everything here is anonymous HTTPS to one host. A proxy that rewrites certificates breaks the signature check, not just the download |

---

## Reference

- `https://downloads.mgt-platform.com/llms.txt`: the whole host in one page,
  endpoints, schemas, the CLI surface and its exit codes.
- `https://downloads.mgt-platform.com/releases/cli/index.json`: the release
  index this skill reads. Take the newest entry that is neither `prerelease` nor
  `withdrawn`; a withdrawn one stays in the document with the reason it was
  pulled, and installing it is a mistake the index is trying to prevent.
- `https://downloads.mgt-platform.com/docs/`: guides and reference. Published on
  Portal releases only, so confirm it is there before sending a reader to it.
