Skip to main content
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:
tilde.toml
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.
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:
The first deploy has three steps: build, give the environment what the build asks for, and deploy.
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. Options for deploy and build: --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

.github/workflows/ontology.yml
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. Bind each slot to one of your organisation’s connections 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.

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

Grant the capability

Allow the tools in the agent’s tools.invoke capability.
4

Permit the agent in policies

Write policies 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. Environments, versions, deployments, spaces, and deploy tokens follow their project.