conductor/docs/ADMIN_GUIDE.md

Administrator Guide

This guide covers administration inside Conductor: accounts, sessions, stored credentials, publications, and execution history. For Docker, TLS, configuration keys, backups, recovery, and upgrades, use the Installation Guide and Operations Guide.

Administrator scope

Conductor has global roles rather than per-project or per-application permissions.

Principal	Access
Anonymous visitor	Active public applications and their anonymous actions only.
User	Public and restricted applications in the catalog; own password change.
Administrator	All user access plus project authoring, validation, action testing, credentials, execution history, publishing, and user management.

The backend enforces these boundaries even if someone constructs an API request directly. Conductor v1.1.0 does not provide groups, custom roles, per-application assignments, self-registration, email invitations, or email-based password recovery.

Initialize a new installation

1. Confirm the host operator has finished the deployment, configured HTTPS, and received a healthy response from /api/health. Independent self-hosters can follow the public installation guide.
2. Open the Conductor HTTPS URL in a browser.
3. On Set up Conductor, enter a unique username and a password of at least 12 characters. Display name and contact email are optional.
4. Select Create administrator. Conductor creates the account and signs it in.
5. Open Users and create a second administrator for recovery before authoring production applications.

There are no default credentials. The browser setup is available only while the database contains no users; it closes permanently after the first account is created. Concurrent setup attempts can create at most one first administrator.

If browser setup cannot be used, the host operator can perform the explicit empty-installation bootstrap in Administrative bootstrap and recovery.

Manage users and sessions

Open Users to perform account administration.

Create an account

Enter a unique username, optional display name and contact email, a temporary password of at least 12 characters, and the User or Admin role. Communicate the temporary password through an approved private channel.

Change an account

• Change Role to promote or demote an account.
• Toggle Enabled to allow or block authentication.
• Edit display name or contact email and leave the field to save it.
• Select Reset password to set and confirm a new password.
• Select Revoke sessions to sign the account out everywhere.

Disabling an account, changing its role, resetting its password, or explicitly revoking sessions invalidates its existing sessions. Conductor refuses to disable or demote the last enabled administrator.

Users change their own password beneath the application catalog. That operation rotates the current session and revokes their other sessions. Administrators can reset their own account from Users, but should keep another working administrator available before doing so.

Account deletion is not exposed in v1.1.0. Disable an account when access should be retained only for historical attribution.

Manage stored credentials

Open Actions & Bindings, then expand Secrets.

Supported credential types are:

• Basic authentication username and password;
• Bearer token;
• API-key header name and value; and
• API-key query-parameter name and value.

To create a credential, select Add secret, choose the type, enter a descriptive name and its required fields, and save. Conductor returns only metadata after creation; the stored value cannot be viewed again.

To rotate a credential, expand it and select Replace value. Enter the complete new credential. Saved project actions retain the same opaque reference.

To remove a credential safely:

1. Find every saved project and active publication that uses it.
2. Remove or replace the reference in each source project, then save the project.
3. Republish each application that should remain live, or unpublish it. Published snapshots are immutable and can retain the old reference until this step is complete.
4. Expand the credential and select Delete.

Deletion is blocked by references in saved projects, but v1.1.0 does not perform that same check against immutable published snapshots. Do not delete first and leave a live restricted application with a missing credential.

Credential values are encrypted with AES-256-GCM using CONDUCTOR_SECRET_KEY. The browser and project JSON receive only opaque secret references, and an existing value can never be retrieved through Conductor. A usable disaster-recovery archive must contain both the database and its matching key. See Backup.

Publish and withdraw applications

Open Publishing after saving and validating a source project.

1. Select the source project.
2. Enter a display name and unique URL slug.
3. Choose a visibility:
   • Restricted to users requires an enabled signed-in account.
   • Public permits anonymous access and is accepted only when every action uses anonymous authentication.
4. Select Publish.
5. Use Open app to verify the default page and at least one direct page URL.

Publishing stores an immutable snapshot. Editing or saving the source project does not change the live application. Select Republish to atomically replace the snapshot with the current valid saved project and increase its version.

Select Unpublish to make the application unavailable without deleting the source project. Republish it to restore access. Active publications prevent deletion of their source project through the backend API.

Published routes are:

/apps/<app-slug>
/apps/<app-slug>/<page-slug>

Restricted visibility applies to the whole application. Page navigation settings are not authorization rules.

Review execution history

Open Execution History to inspect recent REST proxy activity. Records persist across restarts and include safe request identity, timing, outcome, upstream status when available, response size, and a bounded redacted preview.

Conductor retains the newest 1,000 executions globally. It does not store request or response headers, cookies, credentials, raw sensitive query values, DNS answers, or stack traces. Treat this as bounded troubleshooting history, not as an immutable enterprise audit log.

Clear history permanently removes all execution records. Back up the installation first if those records are needed for later analysis.

Proxy and internal destinations

Project authors can call public http and https endpoints that pass Conductor's destination and request policy. Private, loopback, link-local, metadata, and other unsafe address ranges are blocked by default.

An in-application administrator cannot weaken that policy. A host operator may add a reviewed exact origin to CONDUCTOR_PROXY_INTERNAL_ORIGINS; wildcards, URL paths, embedded credentials, and IP literals are not accepted. Use Production configuration.

Recover administrative access

Try these options in order:

1. Ask another enabled administrator to reset the account's password, enable it, restore its role if appropriate, and revoke old sessions.
2. If every administrator is inaccessible, ask the host operator to use the guarded recovery command in Administrative bootstrap and recovery.
3. If application data is damaged or missing, follow the full restore procedure instead of creating unrelated accounts.

Operator recovery can target only an existing local administrator. It cannot elevate a user or create an additional administrator after first-run setup.

Routine administration checklist

• Keep at least two enabled administrators with independently controlled credentials.
• Review active publications and confirm public applications contain no credential-backed actions.
• Rotate upstream credentials using Replace value, then test the affected actions.
• Review execution failures without copying sensitive data into tickets or screenshots.
• Confirm scheduled backups complete, copy them off-host, and periodically test a restore.
• Install upgrades only from pinned images after reading release notes and taking a backup.

For symptom-based help, see Troubleshooting. Product boundaries are summarized in v1.1.0 limitations.

Security boundaries

• Authentication establishes an identity; backend authorization independently checks the account's current enabled state and role on every protected request.
• Passwords use salted scrypt hashes. Sessions are random, server-side, hashed at rest, rotated after sensitive account changes, and protected by secure cookies and CSRF tokens.
• All authoring, validation, credential, history-management, user-management, and publication-management APIs require an administrator. Hiding navigation in the browser is not the security boundary.
• Publishing stores an immutable validated snapshot. Public snapshots may use only anonymous actions. Restricted published clients submit runtime values to server-owned action IDs and never receive draft JSON, secret references, authoritative URLs, or authentication configuration.
• Execution history stores at most 1,000 sanitized records. It excludes request and response headers, cookies, credential values, sensitive query values, DNS answers, private addresses, and stack traces.
• Conductor does not isolate mutually hostile administrators or protect a host whose backend process, database plus encryption key, or operating system has been compromised.

Included with Skeleton Works

Publishing now has separate sections for applications you publish from saved projects and applications installed on the VM. Installed applications appear only after their installer registers them. Use Open to launch one and Configure, when supplied, for its administration screen. Installed applications do not have Republish or Unpublish controls; their installer owns updates and removal.

For the manifest and VM administration commands, see Included applications. Conductor contains no default Social Scheduler entry.

Application icons and browser titles (v1.1.0)

These features are included in Conductor v1.1.0.

Conductor uses its blue C-and-baton icon by default. The browser tab shows Conductor at home, the screen name while editing (for example, Publishing · Conductor), or the application's name (for example, Workshop Notes · Conductor).

To choose an icon when publishing:

1. Open Publishing and select the saved project, application name, address and access setting. This identifies the application being published.
2. Under Application icon (optional), choose a square PNG between 16 and 512 pixels and no larger than 256 KB (262,144 bytes). The preview confirms the image was accepted; leave the field empty to use Conductor's icon.
3. Select Publish, then Open app. The application card and browser tab should show the chosen icon and application name.

To change an existing application's icon, expand Application icon on its Publishing card and choose a PNG. This saves the icon immediately. Select Use Conductor icon to reset it. Reload an already-open application tab to see a changed icon. Republish preserves the chosen icon; changing an icon does not publish changes to the source project or change its access setting.

Uploads are stored with Conductor's database on the customer VM. They need no S3 service. They are public decorative images, including when assigned to restricted applications, so choose a logo or symbol suitable for public display. Uploading an icon requires an administrator session and the same request protection as other administrative changes.

Installed applications receive their name and optional icon from their installer. Their icons are not edited through the project-publication controls. See the installed-application contract.