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

# Configure your environment

> Pick a data-platform strategy for your tenant and set up a git repo for your runbooks.

Two setup steps before you write your first runbook:

1. **Pick a data-platform strategy** when you create the tenant — Ntropii-managed Postgres or your own warehouse.
2. **Set up a runbook git repo** — this is where you and your coding agent will author the Python code.

You only need to do each step once per tenant.

## 1. Pick a data-platform strategy

Every tenant has to declare what data platform it uses at creation time. Three values today:

| If you...                                                            | Pick                     |
| -------------------------------------------------------------------- | ------------------------ |
| Are starting fresh, don't run a warehouse, or want the simplest path | `managed-postgres`       |
| Already run Snowflake for fund-ops data                              | `snowflake` (BYO)        |
| Run Microsoft Fabric and want Ntropii to read from it                | `microsoft-fabric` (BYO) |

The chosen value is stored on the tenant and is the audit answer to "what data platform does this tenant run on?". It's required — there's no implicit default.

<Tabs>
  <Tab title="Use Ntropii Postgres (default)">
    One command. Ntropii provisions a per-tenant Postgres database for you; no credentials to register.

    ```bash theme={null}
    ntro tenant create --slug acme-fund --data-platform managed-postgres
    ```

    The tenant lands in `PROVISIONING` while the database is being prepared, then flips to `ACTIVE`. From that point on, runbooks running on this tenant read from and write to its managed database without any further config.

    <Note>
      Managed Postgres is per-tenant isolated — each tenant gets its own database, not a shared schema. The data sovereignty model is identical to BYO: financial data stays inside Ntropii Tenant, never enters Ntropii Workspace.
    </Note>
  </Tab>

  <Tab title="Bring your own data platform">
    Two steps: register a config (which holds the credentials), then bind it to a new tenant.

    ```bash theme={null}
    # 1. Register the config
    ntro integration add snowflake \
      --name "Acme Snowflake UK" \
      --account acme-fund.eu-west-2 \
      --warehouse fund_ops \
      --user ntropii \
      --password <secret> \
      --region UK-South
    # → dpc_abc123

    # 2. Create the tenant bound to that config
    ntro tenant create \
      --slug acme-fund \
      --data-platform snowflake \
      --data-platform-config dpc_abc123
    ```

    The `--data-platform` value (`snowflake` here) and the config's provider (`SNOWFLAKE`) must match. Ntropii rejects mismatched bindings up front.

    Verify connectivity before deploying any runbooks:

    ```bash theme={null}
    ntro integration list
    ntro integration test dpc_abc123
    ```

    If `test` returns `OK`, the credentials work and the tenant can read from your warehouse.

    <Note>
      The credentials you provide here go straight into Ntropii Tenant — they never enter Ntropii Workspace. The CLI just transports them; Workspace records that an integration exists, but does not store the secret.
    </Note>
  </Tab>
</Tabs>

### Inspect what's available

Once a binding is in place (managed or BYO), you can ask Ntropii to list the schemas it can see:

```bash theme={null}
ntro integration discover <integration-id>
```

This is what your coding agent uses (via MCP) to understand your warehouse layout when generating a runbook.

## 2. Set up a runbook git repo

Runbooks are plain Python files using the `ntro` SDK. They live in a git repo that **you** own — on your own GitHub organisation, with your own commit history. Ntropii does not host your runbook source.

Two repos to be aware of, with different roles:

| Repo                                                                              | What it's for                                                                                                                                      |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[`ntro-runbook-starter`](https://github.com/ntropii-com/ntro-runbook-starter)** | The empty scaffold. Use it once, as the template for your own repo. After bootstrap, your repo lives at *your* org and is yours to evolve.         |
| **[`runbook-templates`](https://github.com/ntropii-com/runbook-templates)**       | Read-only reference library — `nav-monthly`, `document-ingest`, `nav-monthly-journals`. Look at it; copy patterns from it; **don't** commit to it. |

### Bootstrap your repo

<Steps>
  <Step title="Create your repo from the starter">
    On GitHub, open [`ntropii-com/ntro-runbook-starter`](https://github.com/ntropii-com/ntro-runbook-starter) and click **Use this template** → **Create a new repository**. Pick a name (e.g. `acme-runbooks`) on your own organisation.
  </Step>

  <Step title="Clone your repo locally">
    ```bash theme={null}
    git clone git@github.com:your-org/acme-runbooks.git
    cd acme-runbooks
    ```

    You'll see an empty `runbooks/` directory and a README — that's it. You fill it in.
  </Step>

  <Step title="Author a runbook">
    The fastest path: ask a coding agent (with the [Ntro MCP server](/tooling/mcp-server) connected) to scaffold one for you. It reads your tenant + data platform schema, picks a pattern from `runbook-templates`, and writes the runbook into `runbooks/<your-slug>/`.

    Or copy by hand:

    ```bash theme={null}
    # Read-only clone of the reference repo (sibling, not a remote)
    git clone git@github.com:ntropii-com/runbook-templates.git ../runbook-templates

    cp -r ../runbook-templates/runbooks/nav-monthly runbooks/your-nav-monthly
    # then edit templates/{workflow.py,activities.py,models.py} for your tenant
    ```
  </Step>

  <Step title="Test it">
    ```bash theme={null}
    ntro workflow test ./runbooks/your-nav-monthly --scenario happy
    ```

    Sub-second startup; no deploy, no Docker, no Temporal cluster. If the scenarios pass, your environment is correctly set up.
  </Step>
</Steps>

### What a runbook looks like

```
runbooks/
└── your-runbook-slug/
    ├── runbook.md                 # skill definition (see Skill definitions)
    └── templates/
        ├── __init__.py
        ├── workflow.py            # NtroWorkflow subclass
        ├── activities.py          # SDK calls (ai.extract, files.parse, accounting.*, etc.)
        ├── models.py              # Pydantic types for inputs/outputs
        └── requirements.txt       # pinned deps for the worker's per-runbook venv
```

**The `requirements.txt` contract.** When you run `ntro workflow create --path`, the CLI uploads your runbook directory *and* its `requirements.txt`. Ntropii Tenant creates a fresh virtual environment from those exact pinned versions, then registers the workflow with Temporal. Two runbooks pinned to different SDK versions can run side-by-side without conflict.

## CLI configuration

The CLI reads `~/.ntro/config.toml`. Run `ntro auth login` to generate it interactively:

```bash theme={null}
ntro auth login
# Connection name [local]:
# Host [https://api.ntropii.com/v1]:
# API key: <paste>
# Default tenant: acme-fund
```

That writes:

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

[connections.local]
host = "https://api.ntropii.com/v1"
api_key = "ntro_..."
default_tenant = "acme-fund"
```

Multiple environments (local / staging / production) can coexist as separate `[connections.X]` blocks. Switch between them with `-c`:

```bash theme={null}
ntro -c production tenant list
```

Override at runtime via env vars: `NTRO_HOST`, `NTRO_API_KEY`, `NTRO_TENANT`, `NTRO_DEFAULT_CONNECTION_NAME`.

## What's next

<CardGroup cols={2}>
  <Card title="API keys" icon="key" href="/get-started/api-keys">
    How to mint, scope, and rotate the key you just used.
  </Card>

  <Card title="Wire it into a coding agent" icon="robot" href="/tooling/coding-agents/overview">
    Once the env is configured, give your coding agent MCP + CLI access.
  </Card>
</CardGroup>