Self-hosted security

Agent Mask self-hosted runs as a private HTTP service in your infrastructure. Docker Hub is the distribution channel; your deployment controls the runtime boundary.

The core security model is simple: clients send specific text or document payloads to the container, Agent Mask processes them locally, and the response comes back to the caller. The container does not connect to your databases, crawl storage, call Agent Mask servers, or download models at runtime.

Data flow

client or job
  -> POST /mask or POST /mask/sync
  -> Agent Mask container
  -> local detection models and operators
  -> response with de-identified text, entity metadata, and optional documents

Agent Mask only processes payloads you submit to the API.

It does not connect to your warehouse, object store, ticketing system, or internal applications by itself.
It does not scan folders, buckets, databases, or queues.
It does not send input text, extracted document text, entity ledgers, or model output to Agent Mask.
It can return an entity ledger in the response so your application can review what was detected. Treat result metadata as sensitive.

Network requirements

The container does not need outbound internet access at runtime.

The Docker image includes the selected language models and supporting assets. Masking does not download models or call Hugging Face or another external service at runtime.

Direction	Recommendation
Inbound	Expose port `8000` only to trusted callers, such as an internal load balancer, private subnet, or localhost for evaluation.
Outbound	Deny by default. The container does not require outbound internet for masking.
Authentication	Set `API_KEY` when the endpoint is reachable beyond a local developer machine.
TLS	Terminate TLS at your ingress, reverse proxy, service mesh, or load balancer. The container itself serves HTTP.
Diagnostics	Keep `/health` reachable for probes. Restrict `/config`, `/license`, and `/metrics` to trusted operators.

Offline license verification

Self-hosted deployments require LICENSE_KEY for mask processing. The key is a signed token verified inside the container against a public key included in the image.

What that means:

No activation server.
No license phone-home.
The container does not send runtime telemetry to Agent Mask.
No remote revocation check.
Trial and commercial expiry are checked locally.

This design has two operational consequences: expiry depends on the container host’s system clock, and a key cannot be revoked remotely before its expiration. It also keeps license checks aligned with the no-outbound-runtime posture of the rest of the service.

See License keys for trial behavior, commercial keys, expiry, and renewal.

Detection and runtime behavior

The image includes the local processing components for the selected tag:

built-in detection for the selected language or language set
custom-entity support
validators for structured identifiers
OCR and document extraction
identity grouping when the image variant includes it

First startup loads models into memory. GPU deployments should run with --gpus all; CPU evaluation can omit the GPU flag and the runtime will use CPU fallback for detection and document processing.

Runtime defaults that matter for security:

Area	Default
Process user	non-root container user
Error responses	sanitized by default
OpenAPI docs	disabled by default in production image configuration
Mask endpoint auth	unset by default; enabled by setting `API_KEY`
Models	included in the image, no runtime download

Data retention

POST /mask/sync returns the final result directly to the caller.

POST /mask stores asynchronous results in SQLite so callers can poll with GET /mask. In self-hosted Docker deployments, the default store is:

/data/agent_mask.db

Retention depends on how you run the container:

If you do not mount /data, async results are container-ephemeral.
If you mount /data, async results persist across restarts until you prune the database or rotate the volume.
If you need strict retention, mount /data to encrypted storage and set a cleanup process that matches your retention schedule.

Do not put /data on a shared volume unless every caller with access to that volume is allowed to read result records.

Hardening checklist

Use this as the production checklist before exposing the container beyond a local developer machine.

Pin a versioned image tag, not latest.
Record the image digest you deploy.
Restrict inbound access to trusted networks.
Set API_KEY and store it in your secret manager.
Run behind TLS at your ingress or load balancer.
Deny outbound internet unless your platform requires an exception for unrelated infrastructure reasons.
Mount /data only when async-result persistence is needed.
Encrypt the /data volume when mounted.
Use default production error handling; read detailed diagnostics from container logs.
Monitor /health, request status codes, queue behavior, and GPU memory.
Review Agent Mask image releases and upgrade to a fixed version when a release addresses relevant CVEs.

Security review support

Self-hosted deployments use the Agent Mask Docker image. You do not need to build, sign, or publish the image yourself.

For production, follow your normal container approval process: use a versioned image, record the digest, and keep release evidence with your vendor-review records. If your security team needs an SBOM, image signature, provenance, or vulnerability scan for the image you plan to run, contact us with the image tag.