Administering your instance¶

Everything you need to run a Victor instance lives in two top-level items in the navigation: Modules (the Module Manager, where you install and update apps) and Settings (a tabbed page for instance-wide configuration and permissions). They sit next to each other at the bottom of the nav. There are no bespoke admin screens to learn. Each area is an ordinary model rendered by a view — the same building blocks you use when you build your own module — so once you know how one screen works, you know how they all work.

The Settings area¶

Settings is a tabbed page fed by menus. Its child menus render as tabs on one page, and the built-in tabs are:

Tab	What it manages
System Parameters	Instance-wide key/value configuration.
Sequences	Named counters used to generate reference numbers. See System parameters & sequences.
Access Rules	Per-model permissions for each group.
Agents	The agents configured in this instance.
Skills	Reusable instruction sets agents can draw on.
Tools	The tools agents are allowed to call.

Because the page is built from menus, any menu that hangs off Settings shows up here as a tab — including tabs your own modules add. See Adding your own Settings tab below.

Modules is not a Settings tab — it is its own top-level nav item sitting beside Settings, covered next.

Managing apps (Modules)¶

Modules is a top-level nav item — the Module Manager. It lists every app available to this instance and lets you change its installation state. It opens as a card view, one card per app, showing:

Field	Meaning
`shortdesc`	The human-readable name / description.
`latest_version`	The version currently available to the instance.
`author`	Who published the app.
`state`	`installed` or `uninstalled`.

Switch to the list view from the toolbar to also see each app's tech_name — its technical name, used in dependencies and references.

Each card offers up to three actions, and the button you see depends on the app's current state:

Install — makes the app's models, views, menus, and seed data available in the instance. Shown only when the app is not installed.
Upgrade — brings an installed app up to the latest available version. Shown only when the app is installed.
Uninstall — removes an app and its data. Shown only when the app is installed; it asks you to confirm first.

Upgrades are non-destructive

Upgrading keeps your data and any edits you made to seeded records. New fields and records are added; nothing you changed is thrown away. You can upgrade a busy app in place without losing work.

Uninstall cascades to dependents

If other installed apps depend on the one you are removing, those dependent apps are uninstalled first. Uninstalling deletes the app's data, so read the confirmation prompt carefully before you accept.

The buttons themselves are declared in the app's view. This is the same view XML you would write in your own module — a button is simply hidden when it does not apply to the current state:

<button action="install"   string="Install"   invisible="state == 'installed'"/>
<button action="upgrade"   string="Upgrade"   invisible="state == 'uninstalled'"/>
<button action="uninstall" string="Uninstall" confirm="Are you sure?" variant="destructive" invisible="state == 'uninstalled'"/>

How apps get onto your instance in the first place is covered in Publishing & installing.

System Parameters¶

The System Parameters tab holds instance-level key/value configuration — think company name, default currency, an outgoing email address, or an API key for an integration. It is provided by the always-installed base app.

Each parameter is a record with three fields:

Field	Type	Notes
`key`	String	Required. The lookup name your code reads, e.g. `company.name`.
`value`	Text	The stored value. Values are always strings.
`secret`	Boolean	When on, the value is masked in the UI. See Secret values.

You can edit parameters by hand on this tab, and module code reads and writes them through the config SDK. get_param returns the stored string, or the default you pass when the key is unset; set_param creates or updates the row for that key:

from victor import config

# read: returns the stored string, or the default if the key is unset
value = await config.get_param(session, "company.name", "Acme")

# write: creates or updates the row for this key
await config.set_param(session, "company.name", "Globex")

Function	Signature	Behaviour
`config.get_param`	`get_param(session, key, default=None) -> str \\| None`	Returns the stored value, or `default` if the key is unset.
`config.set_param`	`set_param(session, key, value, secret=False)`	Upserts by `key`. Pass `secret=True` to store the value masked.

Secret values¶

Some configuration should not be readable in plain text — API keys, tokens, passwords. Store those with secret=True. The value is masked in the records UI, while your module code still reads it back in the clear:

from victor import config

await config.set_param(session, "api.key", "sk-123", secret=True)  # masked in the UI
key = await config.get_param(session, "api.key")                    # module code sees "sk-123"

Set secrets from code

Create and update secret parameters through config.set_param(..., secret=True) so the value is stored masked. Reading a secret back with config.get_param transparently returns its clear value to your module.

Parameters have no field-level protection

System Parameters have no per-parameter access control — who can view or edit them is governed only by the model-level Access Rules on the system_parameter model. If your instance stores sensitive parameters, restrict system_parameter to a trusted group so ordinary users cannot browse the whole table.

For more on parameters and on Sequences, see System parameters & sequences.

Users and access¶

Victor separates who a user is from what they can do.

Identities and group membership come from Victor Cloud. The instance has no separate login — users sign in through Cloud, and the groups they belong to are carried over with them.
Permissions are granted on the instance, per model, using Access Rules.

Access Rules¶

The Access Rules tab (provided by the security core app) is where you say what each group is allowed to do to each model. A rule maps one group and one model to the four basic operations:

Field	Meaning
`group_name`	The group the rule applies to (a group name carried from Victor Cloud).
`model`	The model the rule governs, e.g. `ticket` or `system_parameter`.
`perm_read`	May read/list records.
`perm_create`	May create records.
`perm_write`	May edit existing records.
`perm_delete`	May delete records.

Two rules decide every access check:

No matching rule means access is denied. A group can only do what a rule explicitly grants it.
Superusers are always allowed, regardless of rules.

So to give the "Support" group full run of a helpdesk ticket model, you add one Access Rule for that group and model with all four operations enabled. To let them read but not delete, enable perm_read/perm_create/perm_write and leave perm_delete off.

Grant the least you need

Because absence of a rule denies access, start narrow and add operations as groups genuinely need them. This applies to admin models too — grant system_parameter, model_access, and the Modules app only to the groups that should administer the instance.

The permission model is described in full in Access control.

Adding your own Settings tab¶

Anything under Settings is just a menu pointing at an action, so a module can add its own admin tab with no frontend code. Declare an action for your model, then add a menu whose parent is the Settings menu, base.menu_settings:

<action id="my_model_action" model="my_model" views="list,form" path="my-model"/>
<menu parent="base.menu_settings" action="my_model_action"/>

That is all it takes — your model appears as a new Settings tab, rendered by the framework using the views you declared. A model can offer several view types (list, kanban, form, and card); when an action lists more than one of list/kanban/card, users switch between them from the toolbar. The Modules view, for example, uses the card view.

Where things live¶

I want to…	Go to
Install, update, or remove an app	Modules (top-level, beside Settings)
Set an instance-wide value or secret	Settings → System Parameters
Configure a reference-number counter	Settings → Sequences
Control what a group can do	Settings → Access Rules
Manage who the users are	Victor Cloud