Aegis Agent

Local installer, hook runtime, and public npm bootstrapper for Aegis ControlTower coding-agent telemetry.

@aegisagentics/agent installs a native aegis-agent runtime, registers supported local agent hooks, and sends safe, governed telemetry to Aegis ControlTower. The npm package is intentionally thin: it does not ship platform binaries. Release binaries are built by CI, checksummed, uploaded to the Aegis website release path, then downloaded and verified during install.

Quick Start

Create an agent installation in ControlTower, then run the generated command:

AEGIS_API_KEY="agk_or_bootstrap_token" npx -y @aegisagentics/agent install \
  --api-base-url "https://stage.0.aegisagentics.com" \
  --otlp-http-base-url "https://otel.stage.0.aegisagentics.com" \
  --installation-id "agent_install_..." \
  --vendors codex

Useful follow-up commands:

aegis-agent status
aegis-agent doctor
aegis-agent flush
npx -y @aegisagentics/agent codex-plugin uninstall
npx -y @aegisagentics/agent uninstall --vendors codex

For local development without downloading a release binary:

cargo build --release
AEGIS_AGENT_BINARY_PATH="$PWD/target/release/aegis-agent" npm exec -- aegis-agent --help

What This Repo Contains

package.json                         Public npm bootstrapper metadata
npm/install.js                       User-facing npx entrypoint
npm/lib/                             Bootstrapper, Codex hook, and release download logic
npm/test/                            Node test suite
npm/release-manifest.json            Publish-time manifest embedded in the npm package
crates/aegis-agent/                  Native Rust runtime
.github/workflows/release.yml        CI release workflow for binaries + npm

Install Lifecycle

1. A ControlTower admin creates an agent installation.
2. ControlTower returns an install command with API base URL, OTLP collector URL, installation ID, and scoped agent key.
3. The npm bootstrapper detects the user's platform.
4. If the native runtime is missing, the bootstrapper downloads the matching release artifact from https://aegisagentics.com/releases/aegis-agent.
5. The bootstrapper verifies byte size and SHA-256 before extracting.
6. The native runtime writes local config and owner-only credentials.
7. Vendor-specific hook files are installed. Codex currently uses both plugin registration and Aegis-owned direct hooks.json entries for reliable local execution.
8. Agent hooks send safe metadata, OTLP facts, queue-backed human-readable logs, and governed capture candidates according to local capture policy.

Local Files

~/.config/aegis-agent/config.json
~/.config/aegis-agent/credentials.json
~/.local/share/aegis-agent/bin/aegis-agent
~/.local/share/aegis-agent/queue/events.jsonl
~/.local/share/aegis-agent/codex-marketplace

credentials.json is written with owner-only permissions on Unix systems. Production installers should move to OS keychain storage where available, but file permissions are enforced today.

Codex Integration

The Codex marketplace generated by this package creates:

codex-marketplace/.agents/plugins/marketplace.json
codex-marketplace/plugins/aegis/.codex-plugin/plugin.json
codex-marketplace/plugins/aegis/hooks/hooks.json

Hook commands point to the installed native runtime:

~/.local/share/aegis-agent/bin/aegis-agent hook --vendor=codex --event=PostToolUse

Codex passes hook payloads on stdin. Command-line arguments only identify the vendor and lifecycle event.

Telemetry Paths

The plugin intentionally separates facts, logs, and artifacts:

| Data type | Path | Notes | | --- | --- | --- | | Run/session/tool facts | Plugin -> OTLP collector -> ControlTower API | Metadata and span facts. Collector forwards agent auth. | | Human-readable logs | Plugin -> API -> queue -> worker -> Postgres | Safe operator log lines only. No raw prompts or tool payloads. | | Capture artifacts | Plugin/gateway -> Capture API -> queue -> worker -> Presidio -> database | Redacted content only after server-side sanitization. |

The local safe queue is removed only after required downstream delivery succeeds. If the collector or API is unavailable, retry with:

aegis-agent flush

Capture Policy

The default capture policy is metadata.

Stored metadata may include:

• vendor and lifecycle event
• vendor event name
• session, turn, trace, and span identifiers
• model and source
• tool name and tool call id
• working directory and transcript path when the agent provides them
• vendor timestamp, status, duration, and raw payload size

Raw prompts, agent messages, tool inputs, and tool outputs are not sent in facts, logs, local queues, or ClickHouse telemetry. If redacted capture is enabled, content candidates are sent to the capture API for server-side Presidio redaction before persistence.

Release Architecture

The public npm package does not contain Rust binaries. Release files live under the Aegis website bucket and are served through CloudFront:

https://aegisagentics.com/releases/aegis-agent/channels/stable.json
https://aegisagentics.com/releases/aegis-agent/versions/<version>/manifest.json
https://aegisagentics.com/releases/aegis-agent/versions/<version>/<platform>/aegis-agent.tar.gz
https://aegisagentics.com/releases/aegis-agent/versions/<version>/<platform>/aegis-agent.tar.gz.sha256

Supported platform keys:

• darwin-arm64
• darwin-x64
• linux-arm64
• linux-x64

The release workflow:

1. Validates the release version against package.json.
2. Runs npm tests.
3. Runs Cargo tests.
4. Builds native release binaries for supported targets.
5. Packages aegis-agent.tar.gz.
6. Computes SHA-256 and byte size.
7. Generates version and channel manifests.
8. Uploads release files under s3://aegis-agentics-website/releases/aegis-agent/*.
9. Invalidates the CloudFront channel and manifest paths.
10. Runs npm pack --dry-run.
11. Publishes @aegisagentics/agent to npm.

GitHub Release Configuration

Required repository secrets:

AWS_ROLE_ARN=<release publisher IAM role ARN from website infrastructure output>
NPM_TOKEN=<npm automation token with publish rights for @aegisagentics/agent>

Optional repository variables:

AWS_REGION=us-east-1
SSM_ROOT_PREFIX=/aegis-agentics

The AWS role is scoped to:

• read the website bucket and CloudFront distribution ID from SSM
• list only the releases/aegis-agent prefix
• put/get objects only under releases/aegis-agent/*
• create CloudFront invalidations

It does not grant general website deploy permissions or S3 delete access.

Publishing a Release

The release workflow runs when a tag matching v*.*.* is pushed. Update package.json, Cargo.toml, and Cargo.lock to the same semver version, commit the change, then push main and the version tag:

git status
git add package.json Cargo.toml Cargo.lock
git commit -m "Release 0.1.0"
git push origin main
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

If main already contains the exact release version, only the tag push is needed:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

Manual release runs are also supported from GitHub Actions with workflow_dispatch; the requested version must still match package.json.

Development

Run the npm tests:

npm test

Run Rust tests:

cargo test --locked

Validate publish contents:

npm pack --dry-run

Useful release-download overrides:

AEGIS_AGENT_RELEASE_BASE_URL="https://localhost/releases/aegis-agent"
AEGIS_AGENT_RELEASE_VERSION="0.1.0"
AEGIS_AGENT_FORCE_BINARY_DOWNLOAD=1

Security Notes

• Do not commit .env, private keys, generated packages, or local credentials.
• The npm files allowlist keeps the package limited to the bootstrapper, README, and generated release manifest.
• Archive extraction rejects absolute paths and .. path traversal.
• Downloaded binaries are size-checked and SHA-256 checked before install.
• Activity logs are intentionally human-readable and metadata-only.
• Tool input/output belongs to the governed capture artifact pipeline, not activity logs.