DEVELOPER GUIDE

Use Aegis to govern your project, or change Aegis itself.

Sections 1 to 4 are for teams putting Aegis in front of an engine. Sections 5 to 9 are for people who extend it. The fastest hands-on start is a project tutorial: each one comes from a kept real run through both front doors.

1. BUILD AND RUN

One Maven build, one runnable jar.

JDK 17 or newer and Maven 3.9 or newer. The default build reaches no external network. Besides embedded Apache Derby and Apache ZooKeeper, it starts one engine process: a Kafka 3.9.1 broker on loopback for the Kafka Admin test.

mvn -B clean install                         # all modules, tests, license headers, coverage gates
mvn -B -Preal-engines clean install          # adds the real-engine validation modules
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config my-aegis.yaml
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config my-aegis.yaml --stdio
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --verify-audit audit/aegis.jsonl
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --verify-audit audit/aegis.jsonl --checkpoints anchor/heads.jsonl
echo -n "$TOKEN" | java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --hash-token
$env:TOKEN | java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --hash-token  # PowerShell
java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --openapi-draft openapi.yaml draft.yaml --source-id orders --base-url https://orders.internal.example
docker build -t aegis-gateway:2.0.0-SNAPSHOT .            # non-root image; plugins go in /opt/aegis/plugins
helm install aegis charts/aegis -f my-values.yaml          # StatefulSet, one audit journal volume per replica

For a Spark Connect source use examples/aegis-gateway-spark/target/aegis-gateway-spark-2.0.0-SNAPSHOT-all.jar, and for the Kafka Admin source examples/aegis-gateway-kafka/target/; the commands are the same. Exit codes of the command-line modes: 0 success, 1 broken audit chain or manifest, 2 usage error. A configuration error stops start-up with a message that names the key.

2. WRITE A CONFIGURATION

Start from the closest profile; unknown keys stop start-up.

Shared profiles live in adopters/configurations/<name>/<name>.yaml (Spark, Spark Connect, Flink, Iceberg, Kafka, an A2A agent, an existing MCP server, and the teaching template template/TEMPLATE.yaml), and 25 adapter profiles in adopters/configurations/adapters/. The minimum file has sources, policy, audit.file and a host section. Every key is in the configuration reference.

StepWhy
Classify every tool with classAn unclassified tool is DESTRUCTIVE; MUTATE and DESTRUCTIVE need an independent per-call approval, and DESTRUCTIVE also a fresh dry-run receipt.
Name the resources each tool touches (resources: [{type, pointer}])Policy rules and scopes match typed resources, not raw arguments.
Give destructive tools a real preview (dryRun)The backend's validate-only flag (ARGUMENT) or a read tool (TOOL) shows the approver the actual target.
List every backend host in egressEvery HTTP destination, including URLs inside arguments, plus Kafka bootstrap and Spark Connect endpoints is checked. Kafka listener addresses advertised after bootstrap need Kafka listener configuration and network policy.
Test policy changes in CI--policy-test <aegis.yaml> <cases.json> evaluates declarative type: http cases without backend, audit or approval. MCP and plugin sources are refused before discovery, and a remote OPA PDP is refused; it exits 1 when a case does not match.
Start a REST API from its OpenAPI document--openapi-draft writes every operation as a DESTRUCTIVE tool with a deny-all policy and lists what it could not express; classify, trim and write policy before use.
Give the backend each user, not one accountcredentials: {type: token-exchange, tokenEndpoint, clientIdEnv, clientSecretEnv, audience} exchanges the caller's verified JWT per call (RFC 8693). Own host with JWT identity only; no fallback.
Pick a secrets.sourceenv (default), file (a mounted directory) or vault (one KV v2 secret). The names in the file stay the same.
Use catalog.mode: REQUIRE_PINS with signed pinsA catalog.manifest signed off the gateway host decides which tool definitions may run.
Add audit.checkpointExports the journal head to storage the journal writer cannot rewrite, so truncation and regeneration are detected.

3. CONNECT A CLIENT OR IDE

Streamable HTTP, stdio, or through Knox.

Generated IDE files differ by client. VS Code includes separate own-host mcp.json and Knox mcp.knox.json variants. Kiro uses one mcp.json with own host enabled and the Knox entry present but disabled. Cursor's generated mcp.json is own-host only. The token supplied to the selected own-host entry decides who the assistant is to Aegis.

4. OPERATE

Approvals, definitions, audit and health.

TaskHow
Decide or inspect an approvalApprovers list pending requests with GET /aegis/v1/approvals and decide with POST /aegis/v1/approvals/{id}/approve or /deny. The requester or an approver may inspect one request with GET /aegis/v1/approvals/{id}, but only the requester receives the single-use token. A requester cannot approve their own request.
Accept a changed definitionGET /aegis/v1/catalog, then POST /aegis/v1/catalog/{tool}/accept with exactly one Aegis-Definition-Digest header copied from the reviewed entry. Signed and configured pins cannot be overridden this way.
Sign the catalog--manifest-keygen <private.pem> <public.pem>, --manifest-create <catalog-reply.json> <manifest.json> <gateway-name>, --manifest-sign <manifest.json> <private.pem>, --manifest-verify <manifest.json> <public.pem> <gateway-name>. Keep the private key off the gateway host.
Sign the server catalog--server-catalog-create <aegis.yaml> <catalog-reply.json> <servers.json>, review it, --manifest-sign <servers.json> <review.key>, --server-catalog-verify <servers.json> <review.pub> <gateway-name>, then set serverCatalog. Only listed sources start; changes apply on restart. Add --serial <n> to refuse older catalogs once this one is accepted, and start the gateway with --require-server-catalog <review.pub> so the configuration cannot drop the catalog.
Contain a server in an incidentWith a separate incident key: --break-glass-create <order.json> <gateway-name> <incident> <minutes> <id>=QUARANTINED|REVOKED, --manifest-sign, --break-glass-verify, set serverCatalog.breakGlass and restart. At most 24 hours; an expired order stops startup. Walk-through: examples/break-glass-mcp-servers/ in the repository.
Check the journal--verify-audit <journal>, or with --checkpoints <file> to also check every exported head. GET /aegis/v1/audit/verify answers verified: true|false to access.auditVerifierGroups.
Probe and measure/healthz; /readyz answers 503 until at least one tool is active; /metrics in Prometheus text, authenticated like /mcp.

5. WHERE TO CHANGE WHAT

Governance lives in the engine; everything else carries it.

You want toChangeDo not
add a control to every callaegis-engine (GovernanceEngine, control/) or a GovernanceHook pluginput governance in a source or a front door
support a backend with a Java clienta module with a ToolSourceFactory (see examples/aegis-spark-connect)add its client to engine, mcp or config
support a REST backenda configuration file with type: httpwrite Java
change protocol handlingaegis-mcp (McpServerHandler, HttpMcpClient, StdioMcpClient)trust a header that disagrees with the body
add a configuration keyGatewayFactory, CONFIGURATION.md and a testaccept unknown keys
change own-host identity, OAuth metadata, routes or CORSaegis-mcp-security (OwnServerSecuritySettings, OwnServerPerimeter, JwtVerifier, SpiffeIdentity)put transport code there; aegis-gateway owns the JDK HTTP binding
add a state or secret providera module with a StateStoreFactory (see aegis-state-derby) or a SecretProviderFactoryweaken the atomic StateStore contract, or skip the egress check
change trace exportaegis-observability-otlplet an exporter block or change a decision
change Knox integrationaegis-knox3-extension onlybundle Knox, Jersey, Jackson or servlet classes

6. EXTENSION POINTS

ServiceLoader interfaces and in-process seams.

InterfaceSelected byContract
config.spi.ToolSourceFactorysources[].typeContributes tool descriptors and executors only. GatewayFactory invokes create(id, settings, context). The default three-argument method delegates to the required two-argument method for compatibility; override the context-aware method when the source needs host services such as context.env().
config.spi.GovernanceHookFactoryhooks[].typeBuilds a GovernanceHook: deny before a call, rewrite or withhold after it.
config.spi.StateStoreFactorystate.typeDurable or shared state; must keep the atomic put-if-absent, take and rate semantics.
config.spi.SecretProviderFactorysecrets.sourceReturns name to value, null for unknown names; receives the egress check and must use it for every destination.
engine.spi.CredentialProviderembedding host (BuildContext)Backend credentials per source, resolved at execution time, never before. Built in: static credentials and RFC 8693 token exchange, which reads the verified caller token from engine.spi.SubjectToken for the duration of the request only.
engine.spi.PolicyDecisionPointbuilt in: rules and OPAAllow or deny with a reason; all configured PDPs must allow.
engine.spi.DecisionListenerembedding hostObserves decisions (metrics, tracing); cannot change them.

Register a factory in META-INF/services/io.github.vaquarkhan.aegis.config.spi.<Interface>. Built-in names (mcp, http, memory, env, file, vault) always select the built-in implementation, and a hook factory that claims a built-in hook name stops start-up.

7. WRITE A SOURCE PLUGIN

Capability only: descriptors and executors.

public final class MyEngineToolSourceFactory implements ToolSourceFactory {
    @Override public String type() { return "my-engine"; }

    @Override public ToolSource create(String id, ConfigNode s) {
        // Compatibility path for direct callers without a BuildContext.
        return create(id, s, System::getenv);
    }

    @Override public ToolSource create(String id, ConfigNode s, BuildContext context) {
        // GatewayFactory calls this overload.
        return create(id, s, context.env());
    }

    private ToolSource create(String id, ConfigNode s, Function<String, String> env) {
        String host = s.requiredString("host");          // read every key you support;
        int port = (int) s.integer("port", 9000);        // unknown keys fail startup
        String tokenEnv = s.requiredString("tokenEnv");
        String token = env.apply(tokenEnv);               // resolve named secrets through the host
        if (token == null || token.isBlank()) {
            throw new ConfigException(s.path() + ".tokenEnv names an unset or empty variable");
        }
        return new MyEngineToolSource(id, host, port, token);
    }
}

8. WRITE A GOVERNANCE HOOK

In another process, or in-process.

Without Java: configure hooks: [{type: remote, settings: {url: ...}}] and answer {"allow": true|false} over HTTP; the URL passes the egress check at start-up. In-process: implement GovernanceHook and ship a GovernanceHookFactory (aegis-mcp-guardrails is a worked example). For the remote path, adopters/hooks has three reference services in Python's standard library (PII guard, secrets guard, change window) with unit tests and a live run against the gateway jar.

9. TESTS AND EVIDENCE

A behavior change comes with a test that fails without it.

BuildWhat runsNeeds
defaultEvery module's unit and integration tests, RAT, per-module JaCoCo floors, the Kafka Admin test against a real KRaft broker, the SPIFFE test over real mutual TLSJDK and Maven
-Preal-enginesReal engines through the own host and, with AEGIS_KNOX_HOME, a stock Knox 3.0.0Engine-specific variables listed in each example README
-Ppostgres-integrationPostgresStateStoreIT, TwoGatewayProcessesPostgresITAEGIS_POSTGRES_URL, _USER, _PASSWORD
-Pvault-integrationVaultKvSecretProviderITAEGIS_VAULT_ADDR, AEGIS_VAULT_TOKEN
adopters/hooks scriptspython -m unittest test_hooks; python e2e_gateway.py --jar ...-all.jar against the running gateway (CI runs both)Python 3 and the built jar
charts/aegis/cihelm lint, helm template with kubeconform, start_rendered.py; CI also builds and starts the imageHelm, kubeconform, Python with PyYAML
-PreleaseThe default build plus release checks and a CycloneDX SBOMJDK and Maven

Rule. A test whose real target is not configured reports skipped, never passed. Protocol fixtures (TestMcpServer) and the adapter contract harness prove protocol and route behavior, not compatibility with a named product. What each run established is in VALIDATION and the claims matrix.

10. TUTORIALS

One per project with a kept real run.

The tutorial index lists the deep-dive tutorials (Spark and Iceberg, Spark and Spark Connect, Iceberg, Kafka, Flink) and one IDE-ready tutorial per verified project, built by tools/build-project-tutorials.py from that project's kept two-door run. Twenty-seven generated tutorials cover the Keep-verified engines, including Airflow, CouchDB, Doris, Druid, Hadoop, HBase, Hive, NiFi, Pinot, Ranger, Storm, and Superset. Projects with a configuration but no real run (Atlas, Cassandra, Impala, Paimon) have no tutorial; they are on the future roadmap.

Security reviewers should start with the HTML security guide (threat zones, TM01 to TM10, OWASP MCP handling, S1 to S31, and dated control-suite records with their attestation status) before reading THREAT-MODEL and SECURITY.

11. CONVENTIONS

From AGENTS.md.