Zum Inhalt

Folder Agent Integration

This document explains how the Newton API and the Windows Folder Agent collaborate to provision directories on a remote SMB/CIFS file share.

Overview

  1. A user (typically BackOffice or Management) calls POST /api/v1/folder-requests via the Newton UI/API with the desired folder path.
  2. The API persists the request as PENDING.
  3. Each installed agent regularly calls POST /api/v1/folder-requests/claim with its API key. The API atomically assigns the job by flipping the status to PROCESSING.
  4. The agent connects to the configured SMB/CIFS share, ensures the destination exists, copies the predefined template structure into it, and reports back using PATCH /api/v1/folder-requests/:id/status with either FULFILLED or FAILED.
  5. Administrators can inspect the queue via GET /api/v1/folder-requests.

API configuration

Variable Description
FOLDER_AGENT_API_KEYS Comma-separated list of agentId:secret pairs, e.g. hq-agent:Z2VtbmlzLXNlY3JldA==,backup-agent:YmFja3VwLXNlY3JldA==. The API guard accepts the secret via the x-api-key header and exposes the corresponding agentId to the controllers.

If only a secret is provided (secret-value), the agent id defaults to the same value.

Agent configuration recap

Set the following environment variables on every agent instance (Windows service or container):

Variable Required Description
FOLDER_AGENT_API_BASE_URL Yes Fully qualified Newton API base URL (e.g. https://api.internal.newton.local/api/v1). Trailing slashes are trimmed automatically.
FOLDER_AGENT_API_KEY Yes API key assigned in FOLDER_AGENT_API_KEYS. Sent via the x-api-key header for every request.
FOLDER_AGENT_SMB_SERVER Yes NetBIOS or FQDN of the SMB server that hosts both the template and project shares. Must match the server portion of the UNC paths below.
FOLDER_AGENT_SMB_USERNAME Yes Service account with read/write permissions on the template and project directories.
FOLDER_AGENT_SMB_PASSWORD Yes Password for the SMB service account.
FOLDER_AGENT_SMB_DOMAIN No Windows domain/realm for the SMB credentials. Leave empty for local accounts.
FOLDER_AGENT_TEMPLATE_PATH Yes UNC path to the template directory (e.g. \\fileserver\templates\project-template). Must reside on the same server as FOLDER_AGENT_ROOT_PATH, but it may reference a different share.
FOLDER_AGENT_ROOT_PATH No Optional UNC root used when requests provide relative paths (2025/ProjectA). When omitted, only absolute UNC destinations are accepted.
FOLDER_AGENT_AGENT_ID No Friendly identifier reported to the API. Defaults to the machine hostname.
FOLDER_AGENT_POLL_INTERVAL_MS No Delay between claim attempts when no work is available. Defaults to 3000.
FOLDER_AGENT_MAX_BACKOFF_MS No Backoff upper bound after repeated failures. Defaults to 30000.
FOLDER_AGENT_REQUEST_TIMEOUT_MS No HTTP timeout in milliseconds. Defaults to 15000.
FOLDER_AGENT_CA_BUNDLE_PATH No Absolute path to a custom CA bundle (PEM). Useful for TLS inspection appliances.
FOLDER_AGENT_ALLOW_INSECURE_TLS No Set to true/1 to disable TLS verification. Use only for troubleshooting.
FOLDER_AGENT_DEBUG No Set to true for verbose logging.

See apps/folder-agent/README.md for further operational guidance.

Containerized deployment

  • The repository ships with apps/folder-agent/Dockerfile and a folder-agent service in docker-compose.yml.
  • Deployments pull the image from ghcr.io/pascalgross/newton/folder-agent via the GitHub Actions workflow.
  • The container connects to the SMB share directly using the credentials above; a host-side CIFS mount is no longer required.
  • When running in restrictive environments you can still mount secrets (e.g. CA bundles) via volumes and point FOLDER_AGENT_CA_BUNDLE_PATH to the mounted file.

Storage provisioning

  • The agent reads the workspace template from FOLDER_AGENT_TEMPLATE_PATH on the SMB share and copies only missing files/directories into the requested destination.
  • Requests may provide a relative path, in which case the agent resolves it against FOLDER_AGENT_ROOT_PATH. Absolute UNC paths are honoured directly after validation.
  • The Windows service should run under a domain/service account that has read/write access to both the template directory and the project root on the share.

Database schema

The new folder_requests table stores the queue:

Column Type Notes
id uuid Primary key.
target_path varchar(4000) Requested folder path (absolute or relative to the agent root).
requested_by_user_id varchar(200) Optional Azure AD object id of the requestor.
agent_id varchar(200) Agent currently processing (filled on claim).
status enum('PENDING','PROCESSING','FULFILLED','FAILED') Current workflow state.
error_message text Last error returned by the agent (if failed).
attempts int Number of times the request was claimed.
created_at / updated_at / processed_at datetime Audit fields.

Indexes on status and agent_id keep the claim operation efficient.

Failure handling

  • Agents employ exponential backoff up to FOLDER_AGENT_MAX_BACKOFF_MS when repeated errors occur.
  • Failed requests remain in the queue (FAILED) for manual intervention. Re-queueing can be done by setting the status back to PENDING via SQL or a future admin endpoint.

Security considerations

  • Agents authenticate exclusively through the API key guard. Rotate keys regularly and prefer long, random secrets.
  • Add network ACLs so only trusted hosts can reach the API endpoint.
  • Optional custom CA bundles allow TLS inspection appliances without disabling certificate validation.