Network-AI
Repository
Security

Data Locations

All files and directories Network-AI creates, reads, or modifies at runtime: paths, purposes, data classification, and retention guidance.

Back to documentation hub Open source file on GitHub
Source file: DATA_LOCATIONS.md

Data Locations

Every file and directory that Network-AI creates, reads, or modifies at runtime — with the path, purpose, data classification, and retention guidance.

All paths are relative to the data directory (default: ./data/, override with --data <path> CLI flag or NETWORK_AI_DATA env var).

Root Data Directory (data/)

File / DirectoryCreated byPurposeData classContains secrets?
audit_log.jsonlSecureAuditLoggerAppend-only event log — every write, permission grant, state transitionSensitiveNo (tokens are hashed)
blackboard.jsonLockedBlackboardPrimary key-value store; all agent coordination stateSensitiveOperator-dependent
pending_changes/LockedBlackboardWAL entries for in-flight propose → commit transactionsSensitiveMirrors blackboard
trust_levels.jsonAuthGuardianPer-agent trust level registrySensitiveNo
.signing_keycheck_permission.pyHMAC-SHA256 key for signing grant tokensCriticalYes
project-context.jsonGoalDecomposerActive project metadata for LLM-assisted goal decompositionInternalNo
backups/EnvironmentManagerPoint-in-time snapshots created by env backup createSensitiveSame as source

pending_changes/ layout

data/pending_changes/
  <changeId>.json        — one file per in-flight proposal

Each file is a BlackboardChange JSON object with key, value, agent, timestamp, ttl, and priority. Files are deleted on commit or abort.

Per-Environment Directories (data/&lt;env&gt;/)

When multi-environment mode is active (NETWORK_AI_ENV=&lt;env&gt; or --env &lt;name&gt;), each environment gets its own isolated copy of all root-level files:

EnvironmentDirectory
devdata/dev/
stdata/st/
sitdata/sit/
qadata/qa/
sandboxdata/sandbox/
preproddata/preprod/
proddata/prod/

Each env directory contains the same set of files as the root data directory. The promotion chain is: dev → st → sit → qa → preprod → prod.

Backup Directories (data/backups/&lt;env&gt;/)

PathCreated byFormat
data/backups/&lt;env&gt;/&lt;timestamp&gt;/EnvironmentManager.backup()Directory copy of the env data dir

Backups are created on demand via network-ai env backup create --env &lt;name&gt;. They are not auto-pruned; use network-ai env backup prune --env &lt;name&gt; --keep N.

Lock Files

FilePurposeLifespan
data/.lockFilesystem mutex for LockedBlackboard atomic operationsHeld for duration of propose/commit; auto-released
data/&lt;env&gt;/.lockPer-environment lockSame

Lock files are created and deleted by LockedBlackboard. A stale lock (process crash) is detected by PID check and automatically cleared.

Audit Log Schema

Each line in audit_log.jsonl is a JSON object. Full schema: AUDIT_LOG_SCHEMA.md.

Key fields:

{
  "timestamp": "2026-05-23T15:00:00.000Z",  // ISO 8601
  "event":     "BLACKBOARD_WRITE",           // event type
  "agent":     "orchestrator-1",             // acting agent
  "key":       "task/result",                // affected key (if applicable)
  "granted":   true,                         // permission outcome
  "tokenHash": "sha256:abc123…"              // hashed token (never raw)
}

Data Classification

ClassDefinitionExamples in Network-AI
CriticalCompromise enables privilege escalation or token forgery.signing_key
SensitiveContains operational data; exposure enables information disclosure or replayaudit_log.jsonl, blackboard.json, trust_levels.json
InternalNon-secret operational metadataproject-context.json, lock files
PublicIntentionally readablepackage.json, source files

Operator Responsibilities

  1. Permissions: Set data/ to 0700 (or equivalent) — readable only by the

Network-AI process owner. The .signing_key file should be 0600.

  1. Secrets in blackboard: Do not store API keys, passwords, or private keys as

blackboard values. The blackboard is plaintext JSON on disk.

  1. Audit log retention: The audit log is never auto-deleted. Implement a log-rotation

policy appropriate for your compliance requirements.

  1. Backup encryption: Backups are plaintext copies. Encrypt at the filesystem level

(LUKS, FileVault, BitLocker) if required by your data-handling policy.

  1. Multi-project isolation: Clear data/ (or use a separate --data path) between

unrelated projects to prevent cross-project context leakage.

Files Never Created by Network-AI

The following are never written by Network-AI and should be treated as suspicious if they appear in the data directory:

  • Executable files (.sh, .exe, *.bat)
  • Private key files in PEM/DER format (.pem, .key, *.p12)
  • Any file outside the data/ directory tree (path traversal is blocked)