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

# Installation

> Install the ntro Python SDK, choose extras, and configure your connection.

The `ntro` SDK is the Python interface to Ntropii. It's what runbooks import (when they run inside Ntropii Tenant) and what the CLI and MCP server import (to talk to Ntropii Workspace on your behalf).

## Install

<Tabs>
  <Tab title="Core (just the client)">
    ```bash theme={null}
    pip install ntro
    ```

    Includes everything you need to call Ntropii Workspace: `Client`, all resource accessors, all Pydantic models, all exceptions.
  </Tab>

  <Tab title="With workflow authoring">
    ```bash theme={null}
    pip install 'ntro[workflow]'
    ```

    Adds `ntro.workflow` (NtroWorkflow, `@runbook.step`), `ntro.ingest`, `ntro.subledger`, all `ntro.capabilities.*` modules, `ntro.events`, `ntro.accounting`, and `ntro.data`. **This is what your runbook's `requirements.txt` should pin** — it's the runtime dependency Ntropii Tenant installs alongside your runbook.
  </Tab>

  <Tab title="With test harness">
    ```bash theme={null}
    pip install 'ntro[testing]'
    ```

    Adds `ntro.testing` (`WorkflowHarness`, `Scenario`, `load_runbook`, auto-mocked activities) on top of `[workflow]`. Use this in your runbook repo's dev dependencies — the `ntro workflow test` CLI command installs this transitively.
  </Tab>
</Tabs>

<Note>
  In a runbook repo, pin `ntro[workflow]` in `requirements.txt` (worker installs this) and `ntro[testing]` in dev dependencies (CI / local iteration).
</Note>

## Quick start

```python theme={null}
from ntro.workspace import Client

# Reads ~/.ntro/config.toml — uses the default connection
client = Client.from_config()

# Or pick a named connection
client = Client.from_config(connection="staging")

# Or be explicit (scripting / testing)
client = Client(
    host="https://api.ntropii.com/v1",
    api_key="ntro_prod_xxx",
)
```

Confirm it works:

```python theme={null}
profile = client.identity.whoami_sync()
print(profile.email, profile.orgId)
```

## Configuration

The SDK reads `~/.ntro/config.toml` (or `$NTRO_HOME/config.toml`):

```toml theme={null}
default_connection_name = "local"

[connections.local]
host = "http://localhost:3000/v1"
api_key = "ntro_dev_key"
default_tenant = "acme-fund"

[connections.production]
host = "https://api.ntropii.com/v1"
api_key = "ntro_prod_xxx"
```

Run [`ntro auth login`](/get-started/api-keys) to populate this file interactively.

### Resolution priority

When `Client.from_config()` runs, it resolves credentials in this order:

<Steps>
  <Step title="Explicit constructor args">
    `Client(host=..., api_key=...)` always wins. Useful in tests where you want zero environmental influence.
  </Step>

  <Step title="Environment variables">
    `NTRO_HOST` / `NTRO_API_KEY`. Useful in CI/CD where you don't want a `config.toml` on disk.
  </Step>

  <Step title="Named connection">
    `Client.from_config(connection="staging")` reads `[connections.staging]` from the config file.
  </Step>

  <Step title="Default connection">
    Falls back to the connection named in `default_connection_name`.
  </Step>
</Steps>

## Async vs sync

Every resource method is async-first with a `_sync` wrapper for scripts and notebooks:

```python theme={null}
# Sync — fine for scripts, notebooks, the CLI
tenants = client.tenants.list_sync()

# Async — for runbooks (Temporal workers run async), high-throughput scripts
import asyncio

async def main():
    client = Client.from_config()
    tenants, workflows = await asyncio.gather(
        client.tenants.list(),
        client.workflows.list(),
    )
    await client.close()

asyncio.run(main())
```

The `_sync` variants call `asyncio.run()` internally — don't use them inside an async function or you'll get nested event-loop errors.

## What's next

<CardGroup cols={2}>
  <Card title="Ntropii client" icon="plug" href="/sdk/client">
    The full surface of `ntro.workspace.Client` — every resource accessor and exception.
  </Card>

  <Card title="Workflows overview" icon="diagram-project" href="/workflows/runbooks/overview">
    `NtroWorkflow` + `@runbook.step` — the SDK primitives runbooks compose.
  </Card>
</CardGroup>