User Manual
Edit / Create Agentic Project
This page allows you to create new automation projects or modify existing ones. Here, you can define project details, manage secure access keys, configure device permissions, and select which of your registered devices the project can interact with.
Edit / Create Agentic Project
Summary
Configure a project for programmatic access — device access as a service via the API — or grant users direct access to devices (Shared device). Define which devices are accessible, set security credentials, and control the exact permissions granted.
Page Access
You can access this page by navigating to: /agentic
Page Functionalities
This page provides the following functionalities and interactive elements:
- Project Key and Secret: These are unique identifiers for your project. For new projects, placeholder text indicates that these keys will be generated upon saving. For existing projects, the actual Project Key and Project Secret are displayed and can be copied. There is also a button to create an email draft containing these credentials for easy sharing.
- Name and Description:
- Project Name: A text field where you enter the name of your project. It requires a minimum of 3 characters.
- Project Description: A text field for providing a detailed description of your project, allowing up to 5 lines of text.
- Select Devices: This section allows you to choose which of your registered devices the project can access.
- Select all devices checkbox: Quickly selects or deselects all available devices.
- Individual Device Checkboxes: Each registered device is listed with its own checkbox, allowing you to select specific devices.
- Set Permissions: This crucial section determines what actions your project can perform on the selected devices. You must choose between two primary access modes:
Allow access via user connections (awaBerry Anywhere)
This mode enables direct device access through awaBerry Anywhere. Users can connect to devices with a standard account ('awaberry') via the terminal. Activating this mode also allows you to enable further options:
- Allow start / stop of Remote Desktop: Users with shared device access can start or stop Remote Desktop (VNC / RDP based) connections themselves.
- Allow start / stop of Web-To-Local Ports: Users can start or stop Web-To-Local Port connections. This is read-only; they cannot add new port configurations.
Allow access via programmatic access (awabBerry agentic API)
This mode is for projects interacting with devices through the awaBerry agentic API. If 'Allow administrator permissions' is checked, the project executes as the root user on Linux systems, recommended for tasks like system configuration. Otherwise, it runs as a standard 'awaberry' user (home directory '/home/awaberry'), recommended for file access or running applications.
- Allow administrator permissions: Grants the project root privileges on Linux-based systems.
- Folder Access:
- Allow access to all folders: Grants unrestricted file system access.
- Limit access to the following folders: Restricts access to specific folders you define. If selected, you can:
- May write to folders: Allows the project to write data into the specified folders.
- May create and write to subfolders: Allows the project to create new subfolders and write into them within the allowed paths.
- Add folder field and button: Enter absolute paths (e.g.,
/home/awaberry/data/) to add specific folders to the allowed list.
- Command Execution:
- Allow all commands: Grants permission to execute any command on the device.
- Limit to the following commands: Restricts command execution to a specific list of commands you define.
- Add command field and button: Enter specific command names to add them to the allowed list.
- Upload/Download Permission Configuration: Buttons located at the bottom-right of the permissions section:
- Upload AgentProject from file: Allows you to load project permission settings from a JSON file.
- Download AgentProject JSON: Saves the current project permission configuration as a JSON file to your device.
- Submission Button: At the bottom of the page, either 'Create project' (for new projects) or 'Update project' (for existing projects) to save your configurations.
Scenario Executions
Possible usage steps within this page:
Here are examples of how you might successfully use this page:
- Create a new project with basic API access:
Configure a project for programmatic access that can interact with one of your devices with standard user permissions and full folder/command access.
- Navigate to the "Edit / Create Agentic Project" page.
- Ensure "Create new project" is displayed at the top.
- Select the "Allow access via programmatic access (awabBerry agentic API)" section.
- Enter a unique name (e.g., "MyAutomationProject") into the "Enter project name" field.
- Provide a description (e.g., "Automates daily reports for my server") into the "Enter project description" field.
- In the "Select devices" section, check the box next to at least one device you want this project to control.
- Keep the "Allow administrator permissions" checkbox unchecked for standard user access.
- Ensure "Allow access to all folders" and "Allow all commands" checkboxes are checked for broad access.
- Click the "Create project" button.
- Observe a success message like "Project created - see project key and secret." and note down the newly generated Project Key and Project Secret.
- Edit an existing project to enable Terminal Access with Remote Desktop permission:
Modify an existing project to allow direct user connections and enable remote desktop capabilities.
- Navigate to the "Edit / Create Agentic Project" page for an existing project.
- Ensure "Edit existing project" is displayed at the top.
- Verify the existing Project Key and Project Secret are displayed.
- Select the "Allow access via user connections (awaBerry Anywhere)" section by clicking its header.
- Check the box next to "Allow start / stop of Remote Desktop".
- Click the "Update project" button.
- Observe a success message like "Project updated."
- Configure limited folder access for an API project:
Restrict an API-enabled project to only access specific directories on a device.
- Navigate to the "Edit / Create Agentic Project" page for an existing project with API access.
- Ensure "Allow access via programmatic access (awabBerry agentic API)" is selected.
- In the permissions section, uncheck "Allow access to all folders".
- In the now visible "Limit access to the following folders" section, type a valid absolute folder path (e.g.,
/home/awaberry/data/) into the "Add folder" field. - Click the "Add" button next to the folder input field.
- Optionally, check "May write to folders" and "May create and write to subfolders" based on your needs.
- Click the "Update project" button.
- Observe a success message like "Project updated."
Possible errors which may occur on this page:
Understanding potential errors helps in troubleshooting:
- Error: "Please select at least one device."
Why it happens: You attempted to save a project without associating it with any devices. Every project needs at least one device to operate.
- Error: "Please add at least one allowed folder."
Why it happens: You chose to limit folder access for an API project but did not specify any folders in the list. The project requires explicit folder paths to access when access is limited.
- Error: "Please add at least one allowed command."
Why it happens: Similar to folder access, if you choose to limit commands for an API project, you must provide a list of allowed commands. The project cannot execute commands if no explicit permissions are given.
- Error: "Invalid folder path."
Why it happens: When adding a folder to the allowed list, the path you entered did not follow the required format (e.g., it must be an absolute path starting and ending with a slash, such as
/home/user/data/). - Error: "Error creating the project - please try again." or "Error updating the project - please try again."
Why it happens: These are general errors that usually indicate a problem with the server communication or your internet connection during the saving process. Check your network and try again.
- Error: "Could not read permissions from provided file."
Why it happens: When using the "Upload AgentProject from file" option, the selected file was either not a valid JSON format or its content did not match the expected structure for project permission configurations.
