Account Management
Account management is used to manage local login accounts for the Flocks WebUI. The open-source OSS edition has only one local admin account. Flocks Pro supports multiple accounts, role management, quota control, and audit of account operations.
1. Edition Differences
| Edition | Account Capabilities |
|---|---|
| Flocks OSS | Local single-account system. During first startup, the bootstrap-admin setup creates the local admin account. The account can then log in, log out, and change its password. |
| Flocks Pro | Multi-account system. Administrators can create admin/member users, change roles, reset passwords, delete users, and are subject to License quotas. Each user has independent session history and a private Workspace directory. |
2. OSS Account Management
2.1 Initialize the Administrator
After the local account system is enabled for the first time, the WebUI enters the initialization flow and requires creation of the admin account. After initialization is complete, all HTTP paths require authentication by default, except for a small number of paths such as static assets, the login page, the initialization page, and channel webhooks.
2.2 Login and Password Change
OSS account capabilities include:
- Login.
- Logout.
- Change the current account password.
- Force password reset after using a one-time password or temporary password.
The OSS edition does not provide multi-member management or a role assignment page.
2.3 Reset the Administrator Password
If you forget the local administrator password in the OSS edition, run the CLI on the machine where Flocks is installed to generate a one-time administrator password:
flocks admin generate-one-time-password --username adminYou can also use the short option:
flocks admin generate-one-time-password -u adminThe command outputs a temporary password. By default, the password is for the administrator account, has a limited lifetime, and requires an immediate password change after first login. It is intended for local operations recovery. Avoid distributing it long-term through chats, tickets, or screenshots.
If you are not sure of the administrator username, list local accounts first:
flocks admin list-users3. Pro Account Management
3.1 Multiple Accounts and Roles
Flocks Pro supports two roles:
| Role | Description |
|---|---|
admin | Administrator. Can manage system-level capabilities such as users, authorization, and audit. |
member | Regular member for day-to-day use of platform capabilities. |
Administrators can view the user list, including user ID, username, role, status, whether a password reset is required, creation time, update time, and latest login time.
When regular users open the account management page, they can only see their own account information. They cannot view, create, modify, or delete other accounts. Regular users also cannot see the audit log navigation.
3.2 Data Isolation and Sharing Scope
Flocks Pro multi-account capability mainly isolates each user's own working context:
| Type | Description |
|---|---|
| Session history | Each user has their own session list and session history. |
| Private Workspace directory | Each user has their own private Workspace directory for personal task artifacts, reports, and files. |
| Shared capabilities | Platform capabilities such as Agent, Skills, Tools, devices, tasks, Workflow, models, and channels are shared by default. |
In other words, multi-account does not copy the whole system into separate tenants. Instead, on the same set of platform capabilities, it isolates personal sessions and personal file space for different users. Team-shared Agents, Skills, tools, devices, and tasks can still be maintained centrally.
3.3 Create Users
When creating a user, enter a username and role. The system generates a temporary password and requires the new user to reset the password after first login.
User creation is limited by License quotas, such as the maximum number of administrators and members. Default quotas can be controlled by Pro authorization or environment variables.
3.4 Change Roles
Administrators can change a user's role to admin or member. The system protects at least one administrator account, preventing the last administrator from being downgraded or deleted.
3.5 Reset Passwords
Administrators can reset passwords for users. During reset, they can generate a temporary password and set must_reset_password, requiring the user to change the password at next login.
If the administrator account password is forgotten, recover it from the server command line with the one-time password command:
flocks admin generate-one-time-password --username admin3.6 Delete Users
Administrators can delete other users, but cannot delete the currently logged-in administrator account or the last administrator.
In the Pro edition, creating users, changing roles, deleting users, and resetting user passwords are mainly completed through the WebUI account management page, and are controlled by the Pro License quota and administrator permissions.
4. CLI Management Commands
Flocks provides the flocks admin command for local account, security, and historical data maintenance. Common commands:
| Command | Purpose | Common Scenario |
|---|---|---|
flocks admin list-users | List usernames, roles, statuses, and latest login times of local accounts. | Forgotten username, account status troubleshooting. |
flocks admin generate-one-time-password --username admin | Generate a one-time temporary password for the specified administrator. The password must be changed after first login. | Forgotten administrator password, administrator account recovery. |
flocks admin generate-api-token | Generate and save a local API Token. | CLI, TUI, or programmatic clients need to access the local Flocks Server. |
flocks admin set-api-token --token <token> | Write the specified API Token to the local secret store. | Multi-end deployment, migration, or unified server Token. |
flocks admin reassign-orphan-sessions --username admin | Assign historical sessions without owner_user_id to the specified administrator. | Clean up historical session visibility after upgrading from single-user to multi-account. |
flocks admin reassign-orphan-sessions --username admin --dry-run | Preview only the number of orphan sessions without writing changes. | Check impact before formal reassignment. |
flocks admin migrate-workspace-to-user --admin-user-id <user_id> | Migrate the historical single-user Workspace to the users/shared two-zone layout. | Migrate historical directories before upgrading to multi-account or Pro Workspace isolation. |
flocks admin migrate-workspace-to-user --admin-user-id <user_id> --dry-run | Preview only the Workspace migration result. | Check outputs, knowledge, and other directories to be moved before migration. |
4.1 Administrator Password Recovery
The most common account recovery command is:
flocks admin generate-one-time-password --username adminAfter running it, copy the temporary password printed in the terminal, log in to the WebUI as admin, and set a new password as prompted. Temporary passwords are only for emergency recovery. After recovery, check whether there are abnormal logins, expired shared links, or exposed terminal records.
4.2 Local Account Inventory
View local accounts:
flocks admin list-usersThe output includes Username, Role, Status, and Last login. The OSS edition usually has only admin; after multi-account is enabled in Pro, more users are shown.
4.3 API Token Management
When local TUI, CLI, or other programmatic clients need to call Flocks Server, generate an API Token:
flocks admin generate-api-tokenIf you need to write an existing Token:
flocks admin set-api-token --token <token>The Token is written to the local secret store for the local service or client to read. Treat it as a login credential and do not commit it to a code repository.
4.4 Historical Session Ownership Cleanup
Sessions created by early CLI, background tasks, or IM channels may not have owner_user_id. After upgrading to multi-account, these sessions may need to be assigned to an administrator:
flocks admin reassign-orphan-sessions --username admin --dry-runAfter confirming the count, run the command for real:
flocks admin reassign-orphan-sessions --username adminThe target user must be an administrator. Run with --dry-run first to confirm the impact before writing changes.
4.5 Historical Workspace Migration
When upgrading from the early single-user Workspace to a multi-account layout, preview the migration first:
flocks admin migrate-workspace-to-user --admin-user-id <user_id> --dry-runAfter confirmation, run:
flocks admin migrate-workspace-to-user --admin-user-id <user_id>This command migrates the historical single-user directory to the users/shared two-zone layout used by multi-account mode, making later Workspace isolation by account possible.
5. Audit Integration
Account operations in Flocks Pro are written to audit logs, for example:
- Create user.
- Change role.
- Delete user.
- Reset password.
These events can be queried in Audit Logs by account, event type, time range, and other conditions.
Audit logs are an administrator capability. Regular users do not see audit log navigation and cannot view other users' account operation records through the account management page.
6. FAQ
6.1 Can the OSS edition create multiple accounts?
No. The OSS edition has only one local admin account. Multi-account capability belongs to Flocks Pro.
6.2 Why did user creation fail?
Common causes include:
- The current user is not an administrator.
- Pro is not enabled or the License is invalid.
- The administrator or member count has reached the authorized limit.
- The username is invalid or already exists.
6.3 Why are some historical sessions not visible?
If a historical session has no auth context, it may not have owner_user_id. The OSS bootstrap admin can usually still see it. A newly added Pro member account may not see these orphan sessions, and an administrator needs to perform ownership cleanup.
Preview the impact first:
flocks admin reassign-orphan-sessions --username admin --dry-runThen perform ownership cleanup after confirmation:
flocks admin reassign-orphan-sessions --username admin6.4 Can an administrator delete themselves?
No. Administrator accounts cannot self-delete. The system also protects the last administrator account to avoid leaving the system with no administrator after all administrators are deleted or downgraded.
6.5 What if the administrator forgot the password?
Run this command on the machine where Flocks is installed:
flocks admin generate-one-time-password --username adminThen use the one-time password printed in the terminal to log in to the WebUI and set a new password as prompted.
7. Related Modules
- Flocks Pro: enable Pro authorization and upgrade management.
- Audit Logs: view account operation records.
- Session Management: accounts affect the visible session scope.