# My Charter Agent Windows Installation Guide

Version: Windows x64 protected package  
Target environments: customer personal computers, Windows Server, and customer-owned private deployments

## 1. Delivery Files

Please make sure you have received the following files:

```text
MyCharterAgent-Windows-x64-Protected-latest.zip
MyCharterAgent-Windows-x64-Protected-latest.zip.sha256
MyCharterAgent-Windows-Install-Guide.zh-CN.md
MyCharterAgent-Windows-Install-Guide.en-US.md
```

If a dated package is delivered, the file names may look like this:

```text
MyCharterAgent-Windows-x64-Protected-20260724-114716.zip
MyCharterAgent-Windows-x64-Protected-20260724-114716.zip.sha256
```

The package does not include the backend source file `app.py`. The backend has been packaged as the Windows executable file:

```text
charter_agent.exe
```

The package also does not include the customer's local `config.json`, SQLite database, archived emails, or runtime logs.

## 2. Runtime Requirements

Recommended environment:

- Operating system: Windows 10/11 or Windows Server
- Architecture: Windows x64
- CPU and memory: 2 vCPU / 4 GiB or above
- Disk: reserve at least 10 GiB of free space; more is recommended if many emails are archived
- Network: the computer or server must be able to access mailbox IMAP/SMTP, HiFleet API, and the configured LLM API
- Browser: Chrome, Edge, or another modern browser

Notes:

- The protected package does not require the user to install Python separately.
- The SQLite database file is created automatically. No separate database software is required.
- If enterprise networks, antivirus software, or firewalls block mailbox IMAP ports, mailbox synchronization will fail. The required network access must be allowed first.

## 3. Verify the Package

Put the ZIP file and the `.sha256` file in the same directory. Open PowerShell, enter that directory, and run:

```powershell
Get-FileHash -Algorithm SHA256 .\MyCharterAgent-Windows-x64-Protected-latest.zip
```

Compare the `Hash` value with the value in the `.sha256` file.

Current package SHA256:

```text
44fbe11583ea97b5c3d3fb30dc0cf1a7890a64c8cd8685b332966cb6ad51cb71
```

If the hash does not match, do not continue with installation. Request a new package.

## 4. Extract the Package

Right-click the ZIP file and choose "Extract All". Use a dedicated directory, for example:

```text
D:\MyCharterAgentInstaller
```

After extraction, the following files should be visible:

```text
charter_agent.exe
config.example.json
install.bat
install.ps1
README_INSTALL.md
README_INSTALL.zh-CN.md
start_agent.bat
stop_agent.bat
uninstall.bat
templates\
```

## 5. Install

Double-click:

```text
install.bat
```

Default installation directory:

```text
%LOCALAPPDATA%\HiFleetCharterAgent
```

This usually maps to:

```text
C:\Users\CurrentUser\AppData\Local\HiFleetCharterAgent
```

The installer creates a desktop shortcut:

```text
My Charter Agent
```

It also creates Start Menu shortcuts for starting, stopping, and uninstalling the application.

Notes:

- The default installation directory is under the current user's profile and does not require administrator privileges.
- Installing to system directories such as `C:\Program Files` requires administrator privileges.
- The installer will not overwrite an existing `config.json` and will not delete an existing `data` directory.

## 6. Start the Service

Option 1: double-click the desktop shortcut:

```text
My Charter Agent
```

Option 2: go to the installation directory and double-click:

```text
start_agent.bat
```

Default URL:

```text
http://127.0.0.1:8765/
```

The startup script opens the local web page automatically in the browser.

## 7. First Login and User Management

When login authentication is enabled, normal users must sign in before accessing the workspace. The first startup automatically creates an administrator account.

If the administrator password was not preset in `config.json`, check the following file in the installation directory:

```text
data\initial_admin_password.txt
```

This file records the initial administrator username and password. After the first administrator sign-in, change the administrator password immediately and keep it safe.

The login page supports Simplified Chinese, Traditional Chinese, English, Japanese, Spanish, German, and Russian. On first visit it follows the browser language by default, and the selected language is saved in the browser.

Administrators can:

- Create normal users in System Settings, including username, initial password, display name, email, and role.
- Reset normal user passwords, deactivate normal users, or delete normal users that are no longer needed.
- Open the "Login Logs" view after "Subscription" on the home page to review recent sign-ins, including time, username, success/failure status, IP address, IP country/city, and browser information.

Recommendations:

- Only administrators can open System Settings. Normal users can browse, search, filter, match, and follow up records in the workspace, but cannot change system-level settings such as mailbox access, LLM, HiFleet API Key, or user management.
- Do not share one administrator account among multiple people.
- Staff should use separate normal user accounts.
- Disable or delete user accounts promptly when staff leave, credentials may have leaked, or the account is no longer needed.
- If the system is deployed on a LAN or public server, also enable HTTPS, firewall allowlists, VPN, or reverse proxy access control.

## 8. Change the Port or Allow LAN Access

By default, the service is only accessible from the local machine:

```text
127.0.0.1:8765
```

To change the port or allow access from other computers on the LAN, edit the following file in the installation directory:

```text
start_agent.bat
```

For example, change:

```bat
set "CHARTER_AGENT_HOST=127.0.0.1"
set "CHARTER_AGENT_PORT=8765"
```

to:

```bat
set "CHARTER_AGENT_HOST=0.0.0.0"
set "CHARTER_AGENT_PORT=8086"
```

Then restart the service.

If the application runs on Windows Server or needs LAN/public access, also allow the port in Windows Firewall and the cloud security group.

## 9. Stop the Service

Option 1: click this Start Menu shortcut:

```text
Stop My Charter Agent
```

Option 2: go to the installation directory and double-click:

```text
stop_agent.bat
```

## 10. System Configuration

After the first startup, an administrator can configure the system on the web "System Settings" page, or edit the following file in the installation directory:

```text
config.json
```

Common settings include:

- Mailbox account, IMAP host, port, SSL, and mailbox password or authorization code
- Mail folders, one folder per line
- SMTP host, port, security mode, and optional SMTP password or authorization code for in-system email replies
- LLM Base URL, API Key, model name, and token limits
- Whether to allow sanitized email subjects and bodies to be sent to the LLM for parsing
- HiFleet API Key
- Whether to enable HiFleet enrichment for private tonnage/cargo records
- Language, subscription and usage, login logs, and related settings

Mailbox folders can be entered one per line or selected from the Settings page with "Fetch Folders". The system connects to the mailbox via IMAP, loads the real folder list, and writes selected folders back to the configuration. This works for both the primary mailbox and additional mailbox accounts. It is recommended when webmail folder names differ from IMAP folder names. If the password field is blank, the saved IMAP credential is used; if a new password is entered before saving, the folder fetch uses that new value for the test.

Private mailbox parsing follows the latest HiFleet mytonnages rules: mixed vessel+cargo emails extract both record types; multiple vessels or cargoes in one email are all stored; Port Line Up, berthing queues, pure news, and pure S&P messages are treated as unknown/exceptions; Laycan/OPEN extraction supports common short forms including `O/A`, `On or ABT`, `At ABT`, `ETABT`, compact ranges, and explicit dates. Vessel type is limited to six standard categories, `Geared/Gearless` is stored only as gear availability, and contact information is redacted before LLM parsing and filled back locally from the original message body.

"Display Days" has moved to the left filter panel. It controls the display window for private open vessels, private cargo, public open vessels, public cargo, matching, and search suggestions, and is saved in the current user's browser. Normal users can adjust it themselves.

On mobile or narrow screens, the page uses a compact responsive layout. Wide tonnage and cargo tables can be dragged horizontally to reveal all columns.

If service-level settings are changed, stop and restart the service.

## 11. Data and Logs

Default data directory:

```text
%LOCALAPPDATA%\HiFleetCharterAgent\data
```

Common files:

```text
data\charter_facts.sqlite3
data\mail_archive
data\server.log
data\initial_admin_password.txt
```

Notes:

- `charter_facts.sqlite3` is the local SQLite database.
- `mail_archive` stores archived raw `.eml` messages for in-system mail preview.
- `server.log` is used for troubleshooting.
- `initial_admin_password.txt` is generated only on first startup when no administrator password is preset. It is used to retrieve the initial administrator account.

## 12. Upgrade

Before upgrading, stop the old service:

```text
stop_agent.bat
```

Back up the following items:

```text
%LOCALAPPDATA%\HiFleetCharterAgent\config.json
%LOCALAPPDATA%\HiFleetCharterAgent\data
```

Extract the new package and run:

```text
install.bat
```

The installer will not overwrite existing `config.json` or the `data` directory by default. Restart the service after installation:

```text
start_agent.bat
```

## 13. Uninstall

Click this Start Menu shortcut:

```text
Uninstall My Charter Agent
```

Or run the following file in the installation directory:

```text
uninstall.bat
```

The current uninstall script stops the service and removes desktop and Start Menu shortcuts. To avoid accidental loss of customer data, it keeps the installation directory, configuration file, SQLite database, archived emails, and logs by default.

If the local data is no longer needed, delete this directory manually:

```text
%LOCALAPPDATA%\HiFleetCharterAgent
```

## 14. FAQ

### 14.1 Nothing Happens After Double-Clicking the Installer

Make sure the ZIP file has been fully extracted. Do not run `install.bat` directly inside the ZIP preview window.  
If it still fails, right-click `install.bat` and choose "Run as administrator".

### 14.2 Windows Shows an Unknown Publisher or Security Warning

The current package is not signed with a Windows code-signing certificate. If the package was received from an official delivery channel and the SHA256 hash is verified, you can choose to continue. For formal public commercial distribution, a code-signing certificate is recommended.

### 14.3 The Web Page Cannot Be Opened

Check:

- Whether `start_agent.bat` has been run
- Whether the URL is `http://127.0.0.1:8765/`
- Whether the port is already used by another program
- Whether antivirus software or Windows Firewall blocks `charter_agent.exe`
- If the port was changed, whether the browser URL uses the same port

### 14.4 Mailbox Synchronization Fails

Check:

- Whether the IMAP host, port, and SSL settings are correct
- Whether an app-specific password or authorization code is used, or whether the provider allows IMAP/SMTP with the mailbox login password
- If only in-system replies fail, check SMTP host, port, security mode, and SMTP password or authorization code; when SMTP is unavailable, reply in webmail while IMAP sync remains unaffected
- If the folder name is uncertain, click "Fetch Folders" in Settings and select folders from the IMAP list to avoid localized folder-name mistakes or folder-not-found errors
- Whether IMAP/SMTP is enabled for the mailbox
- Whether the current computer or server can access the mailbox IMAP port
- Whether enterprise network policies block external mailbox access

### 14.5 LLM Parsing Fails

Check:

- Whether the LLM Base URL is correct
- Whether the LLM API Key is valid
- Whether the model name is correct
- Whether sending sanitized email subjects and bodies to the LLM is allowed
- Whether the input and output token limits are sufficient

### 14.6 HiFleet Enrichment or Public Tonnage/Cargo Search Fails

Check:

- Whether the HiFleet API Key is correct
- Whether the account has an active subscription or sufficient point balance
- Whether "HiFleet enrichment for private tonnage/cargo" is disabled
- Whether the current tonnage or cargo record contains enough information for enrichment

## 15. Security Recommendations

- Deploy on the customer's own computer, internal server, or customer-owned cloud server.
- Mailbox passwords, LLM keys, and HiFleet API keys should be configured and managed by the customer.
- Do not share the same Windows login account among multiple users.
- Do not share one system administrator account among multiple users. Normal users should use separate accounts, and accounts should be disabled or deleted when staff leave or no longer need access.
- Change the administrator password after the first sign-in. If external access is enabled, combine HTTPS, firewall allowlists, VPN, or reverse proxy authentication.
- If the customer does not want private tonnage/cargo information sent to HiFleet, disable "HiFleet enrichment for private tonnage/cargo" in Settings.
- If the customer does not want email content sent to a public LLM, disable LLM email parsing authorization or use a customer-owned private LLM.
- If the service must be exposed externally, add VPN, reverse proxy authentication, Windows Firewall allowlists, or other access controls.
