Access, permissions and data¶
In short
- ParleML runs in open mode (no sign-in) until you turn sign-in on with
PARLEML_AUTH_REQUIRED. With an SSO issuer, people sign in as themselves. - Three kinds of caller reach ParleML: people, the agent sessions ParleML runs, and your own agents or scripts with a token.
- No token can promote, release or delete anything. Those acts are always a person's.
- Everything ParleML keeps lives in one directory, the data root. Back it up as a whole.
Who can sign in¶
Settings → Access shows the sign-in mode, and Settings → Diagnostics repeats it.
| Mode | What it means |
|---|---|
| Open mode | Sign-in is off. Anyone who can reach the server can use it. It suits a personal or local installation behind your own network controls. |
| Single sign-on | PARLEML_AUTH_REQUIRED=true and an SSO issuer are set. People sign in through your identity provider and act as themselves. See Set up single sign-on. |
| API tokens only | PARLEML_AUTH_REQUIRED=true without an SSO issuer. Nobody can sign in in the browser; only API tokens work. |
Administrators see every page under Settings. Everyone else sees Access only: the sign-in mode, the setup for their own agent, and their connected agents. Pages that record who did something, such as approvals or a dataset's creator, show anonymous in open mode.
Three kinds of caller¶
| Caller | How it authenticates | What it can do |
|---|---|---|
| A person | The browser session, or the open-mode user | Everything in the application that the person's role allows, including every consequential act. |
| An agent session that ParleML runs | A token made for that session, which records where it came from, limited by the workspace's profile | What its profile and skills grant: read, compute and build inside its workspace. |
| Your own agent or a script | An OAuth connection or an API token | Only what its scope allows. |
ParleML never puts a person's credentials in an agent's hands. Each agent CLI runs under the server's own login, and ParleML never stores or shows the CLI's keys.
Connect your own agent¶
An agent host that supports OAuth (claude.ai, ChatGPT and others) connects with no token to paste: you approve it in the browser. Its access lasts an hour and renews by itself. Each connection is listed under Connected agents on Settings → Access, and you can disconnect it at once.
Other clients use an API token. Only an administrator creates API tokens, on Settings → Access. The token's value is shown once, and only its hash is kept.
API token scopes¶
A token has one of three scopes. Each scope includes the one before it.
| Scope | Allows |
|---|---|
| analyst (default, read-only) | Every read: catalog, read-only SQL, profiles, EDA, evaluation, insights, charts, rules, AutoDoc, run status and comparisons. |
| compute | The reads, plus bounded computation that changes nothing: signal checks, single-record predictions and what-if, decision simulations, dataset comparisons. |
| builder | The above, plus building inside the workspaces the token is bound to: recipes, column roles, EDA and leakage reviews, experiments from a plan, explanations, publishing, batch scoring, release records, intended use, importing a model and registering a model. |
A builder token is bound to named workspaces, has a budget and expires:
- Budget: by default 2 runs at once and 20 runs a day, and plans no larger than medium in size.
- Expiry: 30 days by default, 90 at most.
Prefer an OAuth connection where your agent host supports it, because its access is short-lived and renews by itself.
What no token can do¶
Authorisation fails closed. Whatever its scope, a token cannot:
- promote or release a model, or move a model between stages;
- delete anything;
- rerun an experiment in place, which replaces its trained artefacts (a retrain is a new plan);
- change settings or connections, or create other tokens;
- download files such as the fitted pipeline, scoring outputs or the model package.
These are a person's acts in the interface. This holds even if an agent is manipulated by text in the data it reads. Everything a builder token creates is audited.
Permissions within the application¶
| Act | Who |
|---|---|
| Read results, run explanations, compare | People, and agents with a suitable scope |
| Create datasets, experiments and reports | People, and builder-scope agents in their workspaces |
| Answer a decision an agent asked | People only |
| Approve a release, promote or archive a model | People only |
| Delete a dataset, experiment, model or workspace | People only |
| Edit profiles, packs and connections | Administrators |
| Create API tokens | Administrators |
| Connect or disconnect your own agent through OAuth | Each person, for themselves (administrators see everyone's) |
The workspace's risk level and intended use do not enforce anything by themselves. They are the record of what the work is allowed to be, which approvals and reviewers refer back to.
How the data is organised¶
ParleML keeps its state in one directory, the data root. Settings → Workspaces & data
shows where it is. In the Docker image it is /app/data_root, on the data volume.
| Kept | Where |
|---|---|
| Each workspace: its datasets, experiments, models and knowledge bases | <data root>/workspaces/<workspace id>/ |
| Published documents, with every version | <data root>/workspaces/<workspace id>/documents/ |
| The catalog: the index the lists and search read | <data root>/catalog.db. Rebuild on Settings → Workspaces & data recreates it from the files. |
| Settings: connections, profiles, skill packs and your skill edits | <data root>/config/ |
| Secrets for connections, and the pseudonymisation key | <data root>/config/vault.json, encrypted with <data root>/.secret_key |
| Agent sessions: transcripts, events and the agents' work files | <data root>/agents/. A session keeps no database, only files. |
| Users, API tokens and personal preferences | users.json, api_tokens.json, user_prefs.json in the data root |
| MLflow runs, when no MLflow connection is set | <data root>/mlflow/ |
The objects form one hierarchy:
workspace
├── knowledge base ── recipes ──► prepared dataset
├── datasets ──► experiments ──► registered models
├── sessions (agent work) ── steps, decisions
└── documents (published reports)
An experiment records the dataset, the configuration and the run that produced it. A model records its experiment, and a published document records its session. You can walk from a model back to the data and the conversation that led to it.
Backups and moving¶
Stop ParleML, then copy the whole data root. Install and operate ParleML gives the commands for the Docker volume.
Keep config/vault.json and .secret_key together. A model that pseudonymises identifier
columns (card numbers, emails, phone numbers, IP addresses) can only score with the key it was
fitted with, and that key is in the vault. Losing either file means refitting those models and
entering every connection's secret again. Keep both out of shared backups.
What stays when you delete¶
Deleting a session's transcript leaves its summary, and leaves the experiments, models and published documents it made. Deleting a workspace removes it from the lists, but a session's files can stay on disk until you remove them. Delete a workspace's sessions first if they should go too.
For the file layout, restart behaviour and security model in full, see Data on disk, Operations and security and the security model.
Next¶
- Set up single sign-on: people sign in as themselves.
- Install and operate ParleML: volumes, backups, upgrades and the server's environment.