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

# Deploy and environments

> Create an ontology project and its environments, deploy from your repository or CI with the tilde CLI, bind connections, set secrets, roll back, and give agents the ontology as tools.

An **ontology project** is one repository. An **environment** is an isolated place where one version of it runs, such as `staging` or `production`, with its own data, connections, and secrets. A **version** is an immutable build of one commit. Deploying rolls a version out to an environment.

## Create a project and an environment

**1. Create the project**

In **Ontology**, select **Create project**. Use lowercase letters, digits, and dashes, such as `crm`. Choose the team that owns it, or the whole organisation.

**2. Name it in the repository**

Add `tilde.toml` at the root of the repository, with the same name:

```toml tilde.toml theme={"system"}
name = "crm"
```

**3. Create an environment**

Open the project, select **Environments**, then **Create environment**, and name it, such as `production`. Switch on **Serve its spaces in Live** if people should open its [spaces](https://trytilde.ai/docs/ontology/spaces.md).

**4. Issue a deploy token**

On the environment, select **Issue deploy token**, and name it after where it will be used, such as `GitHub Actions`. Tilde shows the token once.

A deploy token deploys exactly one environment of one project. Store it as a CI secret, and revoke it from the environment's **Deploy tokens** list.

## Deploy

The `tilde ontology` commands run from the project's directory. They upload the committed `HEAD`, and read two environment variables:

```bash theme={"system"}
export TILDE_URL="https://<your-tilde-cloud-url>"
export TILDE_DEPLOY_TOKEN="<deploy token>"
```

The first deploy has three steps: build, give the environment what the build asks for, and deploy.

```bash theme={"system"}
tilde ontology build --environment production
# Version 2b1f…: ready
#   connection slot stripe: bind it to a stripe connection
#   secret PARTNER_API_KEY: set it (tilde ontology secrets set)

printf '%s' "$PARTNER_API_KEY" | tilde ontology secrets set PARTNER_API_KEY --environment production
# bind the stripe slot in the environment's settings, then:

tilde ontology deploy --environment production
```

A deploy that would leave a slot unbound or a secret unset is refused before it starts, and names each one. Later deploys are one command.

| Command | Does |
| - | - |
| `tilde ontology build --environment <env>` | Builds `HEAD` into a version without deploying it, then lists unbound slots and unset secrets. |
| `tilde ontology deploy --environment <env>` | Builds `HEAD` and rolls it out. |
| `tilde ontology status --environment <env>` | Each pipeline's last sync, rows, freshness, and errors, and each model's last run. Add `--json` for the raw status. |
| `tilde ontology run --environment <env>` | Ingests what is new and builds models now. `--select` narrows it, `--full-refresh` starts over. |
| `tilde ontology backfill --environment <env> --start 90d` | Ingests and rebuilds a window again. |
| `tilde ontology versions` | Lists the project's versions, and marks the one the environment runs. |
| `tilde ontology rollback --environment <env> --version <id>` | Deploys an older version again. |
| `tilde ontology secrets set\|list\|delete --environment <env>` | Manages the environment's secrets. |

Options for `deploy` and `build`:

| Option | Effect |
| - | - |
| `--allow-dirty` | Deploys `HEAD` even with uncommitted changes. They are not included. |
| `--accept-rebuild model:<name>` | Accepts a model rebuild that the deploy would otherwise refuse. Repeatable. See [When a deploy rebuilds a model](https://trytilde.ai/docs/ontology/sources-and-models.md#when-a-deploy-rebuilds-a-model). |
| `--timeout <seconds>` | How long to wait for the build and rollout. Default `1800`. |

`--select` takes pipelines, `<pipeline>.<stream>`, and models. `x+` adds everything downstream of `x`, and `+model` everything upstream of the model.

The same commit always builds to the same version. One rollout runs at a time per environment, and the latest succeeded deployment is active.

### Deploy from CI

```yaml .github/workflows/ontology.yml theme={"system"}
name: Deploy the ontology
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Install the tilde CLI here.
      - run: tilde ontology deploy --environment production
        env:
          TILDE_URL: ${{ vars.TILDE_URL }}
          TILDE_DEPLOY_TOKEN: ${{ secrets.TILDE_DEPLOY_TOKEN }}
```

You can also build any branch, tag, or commit from the project's **Versions** tab, with **Build from ref**, when the project has a repository URL. Compare two versions there to see what changed, and everything downstream of it.

## Connections

The environment's **Connections** section lists the project's [connection slots](https://trytilde.ai/docs/ontology/sources-and-models.md#connection-slots). Bind each slot to one of your organisation's [connections](https://trytilde.ai/docs/connections.md) of the slot's provider, or set up a new connection from there.

Binding a slot needs `edit` on the project and `view` on the connection. Unbinding a slot cuts off access within minutes. Different environments can bind the same slot to different accounts, such as a sandbox account for `staging`.

## Secrets and settings

**Secrets** are values you provide that are not a third-party account: a database password in `ducktail.toml` (`${APP_DB_PASSWORD}`), or an ontology `secret()`. Set them in the environment's **Secrets** section, or with `tilde ontology secrets set <NAME>`, which reads the value from standard input. Secrets are write-only: Tilde lists their names, never their values. The next deploy reads them. Names starting with `TILDE_` or `DUCKTAIL_` are reserved.

**Settings** are plain values declared with `setting(default)`. They keep their defaults unless the environment overrides them through the management API.

## Registry events

Switch on **Registry events** in the environment's settings to deliver your organisation's chat threads, messages, and other Tilde data to the project's `tilde` pipeline. See [Tilde chat events](https://trytilde.ai/docs/ontology/sources-and-models.md#tilde-chat-events).

## Give an agent the ontology

The **Tilde Ontology** tool provider gives agents an environment's reads and actions as tools. The connection holds only the environment's ID, and no key: Tilde issues a short-lived token for each call, and the ontology's policies decide it.

**1. Connect the environment**

In **Tools**, select **Connections**, then **Tilde Catalog**, and choose **Tilde Ontology**. Select **Add account**, and enter the environment's ID.

**2. Add it to the agent**

Open the agent in the Agent Registry, select **Tools**, then **Add tool**, and choose the connection. Switch on the tools the agent should use. See [Manage tools](https://trytilde.ai/docs/tools/management.md#choose-an-agents-tools).

**3. Grant the capability**

Allow the tools in the agent's `tools.invoke` [capability](https://trytilde.ai/docs/iam.md#agent-capabilities).

**4. Permit the agent in policies**

Write [policies](https://trytilde.ai/docs/ontology/policies.md) for `principal.type == "agent"`, or for the specific agent.

The tool list follows each deploy. A call the policies deny reaches the agent as the tool's error. Give each agent only the tools its role needs, and keep its policies just as narrow: both are enforced.

## Who can do what

Ontology projects have their own [operator roles](https://trytilde.ai/docs/operator-access.md#operator-roles). Environments, versions, deployments, spaces, and deploy tokens follow their project.

| Action | Lets a person |
| - | - |
| `view` | See the project, open its spaces in Live, and read environment status. |
| `edit` | Change the project and its environments: connections, secrets, runs, and backfills. |
| `deploy` | Build, deploy, roll back, activate spaces, turn on registry events, and issue deploy tokens. |
| `share` | Grant roles on the project. |
| `write_streams` | Write records to the project's [custom streams](https://trytilde.ai/docs/ontology/sources-and-models.md#custom-streams). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.