northpoint-agent

Client-side bridge for Northpoint. Run on a server inside your organization's network so a cloud-hosted Northpoint runtime can read your local files / databases without you having to open inbound ports.

The agent makes one outbound WSS connection to your Northpoint cloud URL, authenticates with a long-lived bearer token, and answers RPC requests for filesystem access. Reconnects automatically with backoff.

Install

npm install -g northpoint-agent

Configure

Two environment variables:

| Variable | Example | Notes | | ------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- | | NORTHPOINT_CLOUD_URL | wss://app.northpoint.financial | The runtime your org admin gave you. | | NORTHPOINT_AGENT_TOKEN | agt_…64 hex chars… | Issued from /config → Agents in your org's admin panel. | | NORTHPOINT_AGENT_ROOT | /mnt/team-data | Optional sandbox. When set, every fs.* call must resolve to a path inside this prefix or it's rejected with PERMISSION_DENIED. Symlinks pointing outside trip the guard. |

The token is shown to your admin once. Store it securely (e.g. systemd EnvironmentFile= referencing a 0600-perm file).

Run

northpoint-agent

The agent prints a single timestamped line per lifecycle event (connect, disconnect, RPC error). On connection drop it backs off with full jitter, capped at 30 s.

What the agent does

• Lists directories the cloud asks about (fs.list).
• Stats and reads files the cloud asks for (fs.stat, fs.read).
• Watches paths for changes (fs.watch / fs.unwatch) — push events land in v0.2.
• Reports the host's basic info on request (system.info).

The agent only does what the cloud asks of it. It cannot initiate arbitrary requests; it doesn't read state on its own.

Sandboxing

The agent runs as the OS user that started it. The simplest way to limit what it can see is to run it under a dedicated non-root user that only has read access to the directories you want exposed. A future NORTHPOINT_AGENT_ROOT env will enforce a path prefix in code as well.

License

UNLICENSED — for use with your Northpoint deployment only.