Documentation

Security model

Nomad touches the most sensitive parts of an agent: its credentials, its permissions and files you have tuned by hand. These are the rules it follows.

Local first

All reading, writing, packaging, backups and history happen on your machine. There is no account and no server. The web interface runs on 127.0.0.1, requires a session token issued by nomad ui, rejects requests whose Host or Origin is not local (which blocks DNS rebinding and cross site requests), and is not reachable from other machines. The public website exposes no file access at all; its inspector reads packages inside your browser.

Secrets

• Before export, import and migration, Nomad scans every text field for API keys (OpenAI, Anthropic, OpenRouter, GitHub, GitLab, Google, AWS, Slack, Stripe, Hugging Face, Telegram), private keys, JSON web tokens, passwords in connection strings and credential assignments.
• Findings show the rule, file and line, never the value.
• Detected secrets are replaced with markers such as [REDACTED:openai-key]. MCP environment variables and headers that hold credentials become references you reconnect at the destination.
• Credential files (.env, keys, auth.json and similar) are left out. Platform secret stores such as ~/.hermes/.env or ~/.openclaw/credentials are never read.
• Keeping secrets requires --include-secrets, prints a warning and is recorded in the package manifest.

Permissions never widen silently

Nomad reads the destination's permission policy before a migration and computes what it would be afterwards. If any capability becomes broader, a new allow rule appears, or a deny rule disappears, the migration stops until you approve that specific change. When a restriction cannot be represented at the destination (for example a browser deny rule in Claude Code) it is listed as not enforced. When a mapping is inexact Nomad picks the stricter option: a source that ran without prompts still gets approval prompts for shell commands in Claude Code and Codex.

Files

• The source agent is only read.
• Every change is shown as a preview first, with a diff per file.
• Shared files are merged at the key or section level. Content outside Nomad's marked sections is never removed.
• Nomad records a hash of everything it writes. A file you edit afterwards is detected and not overwritten without approval.
• All affected files are backed up before writing. Writes are atomic (temporary file and rename). If any write fails, the files already written are restored.
• If the destination changes between preview and execution, the run stops.
• Writes never follow symbolic links below the destination folder.
• Imported routines are always paused.

Packages

A package is never trusted, even one Nomad created. Before anything is extracted, the archive directory is checked for path traversal, absolute paths, backslashes, control characters, symbolic links and special files, duplicate paths, encrypted entries, unexpected file types, size limits and compression ratios. Entries are then inflated with their declared size as a hard cap, and every file is checked against the SHA-256 recorded in the manifest. Scripts inside skills are stored and reported but never executed.

Assistants

The MCP server is read only by default. With --allow-writes an assistant can apply a migration only by quoting the token of a preview, so it cannot write anything that was not previewed. Replace mode, overwriting edited files and broader permissions additionally require --allow-replace.

Remote migration

The experimental nomad remote push command uses your system ssh and scp with strict host key checking. An unknown host fails with instructions to verify its fingerprint; Nomad never turns the check off and never reads your private keys.

Reporting a problem

Please report security issues privately through GitHub security advisories, not in public issues.