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.0.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.0.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.0.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 CONDUCTOR_SECRET_KEY. A usable disaster-recovery archive must contain both the database and its matching key. See the Secrets Security Model and Backup and restore.

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 and URL paths are not accepted. Use the procedure for the deployment style in Production configuration and the detailed Proxy Security Policy.

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. For implemented boundaries, see Known Limitations.