Build on Ophiolite

Everything an application needs is public: this page, the API description every deployment serves (/api/v1/openapi.json), the documentation index for agents and the SDK.

1. A key and the SDK

A key belongs to one project, so you need a project first. An owner of an organization creates one in the Workspace: Projects → New project in that organization (Access and assets says what the creator may then do). Someone who owns no organization asks the deployment’s operator, who lets them create organizations with ophiolite-ops project-creator <user>; they own each organization they create, so they can create its projects. The SDK and the ophiolite command cannot create a project yet.

Create a project access key on your account page under Project access keys (it inherits your own access to one project; it is shown once). Give each application its own key and name the key after the application: whatever the application publishes with it, Workspace and the API record which access key published it: Workspace says “through an access key” beside you as the author, and the key’s name is in Technical details. This records the key, not a verified application. Then:

pip install "ophiolite @ git+https://github.com/tuna-soup/ophiolite-sdk@<the commit llms.txt names>"
export OPHIOLITE_ACCESS_KEY=oph_key_...
ophiolite projects --url https://ophiolite.example --json

This installs the Ophiolite SDK of release 2026.11.18.

Exact version

ac62ad00e2fe399756474cd655ee6b750966dd88

The project commands (ophiolite wells, entities, changes, sources) read configuration.json in the current folder: the address and the project, nothing secret. Write it once (the project’s Settings → Build on this project → Technical details shows it filled in):

echo '{"schema": "ophiolite.local-configuration/1", "url": "https://ophiolite.example", "project": "<project id>"}' > configuration.json
ophiolite wells list --json

With OPHIOLITE_ACCESS_KEY set and no saved sign-in, the commands use the key.

In Python, Client(url, project, Credential.bearer(os.environ["OPHIOLITE_ACCESS_KEY"])) is the client every recipe below uses. Every command takes --json; exit codes and dry runs are described with the command line. Every refusal carries a code, what to do and a request id — see Errors.

Service accounts for shared jobs

A project access key belongs to the person who made it and stops when that person leaves the project. For work that must keep running when people move on (a nightly import, a morning report), a project administrator creates a service account in the project’s Settings → Service accounts, chooses what it can do (Can read or Can read and publish) and names at least one administrator for it. Its administrators make and remove its keys there; a key is shown once, and the SDK uses it the same way (OPHIOLITE_ACCESS_KEY or ophiolite login --key). A long read of a seismic volume runs on such a key for as long as the key is valid (Long reads).

A service account works in its own project only and never administers it. What it publishes is recorded as done for the project by the account, “on behalf of” the project, not of the person who made the key. A project administrator can disable it at any time; its keys stop at once and its record stays. Someone who is the only administrator of a service account cannot be removed from the project until another administrator is named; a screen that hands a leaver’s own keys and jobs over to a service account is planned.

2. A sandbox with data

To try this without touching a real deployment, start a disposable sandbox with three provinces of public NLOG well headers and three people who see different wells:

ophiolite-ops dev up --fixture nlog-provinces

Run it in your deployment’s package folder (it uses the release named in .env; elsewhere pass --image). It prints each person’s project access key and Workspace sign-in token once (--json prints them as one JSON object). Alice sees the wells of Groningen and Drenthe, Bob those of Drenthe and Friesland, and Eve none: each well is located by its row in its province’s table, which the sandbox administrator shares only with the people who may read that province. It also prints a read key for the sandbox administrator, labelled “ophiolite operator”, who selected the province tables as sources: with it, Read a connected source in Python reads the Groningen table’s 661 rows. ophiolite-ops dev down removes only this sandbox.

3. Recipes

Journey	Recipe
Wells on a map	Wells on a map — ophiolite init map-application
Read curves in Python	Read curves in Python
Formation tops in another application	Formation tops in another application
Publish a result you computed	Derive and publish — ophiolite init derive-and-publish
Keep in step with Workspace	Keep in step with Workspace — ophiolite init sync-worker
Read a connected source	Read a connected source in Python — ophiolite sources read; see also Source rows and project wells
Correct a well’s position	Correct a well’s position — client.publish_derived(..., of_entity=...), kept beside the copy it corrects

Each recipe runs as written in the conformance suite, so an example that stops working fails a check.