Getting Started

Operator quickstart for the Federal Frontier AI Platform — accessing Compass, querying infrastructure, and understanding results.

Getting Started

This guide gets platform operators up and running with the Federal Frontier AI Platform. You will learn how to access Compass, ask questions about your infrastructure, and interpret the results.

Accessing Compass

Compass is the AI-powered interface to the platform. Open your browser and navigate to:

https://compass.vitro.lan

You will see the Compass dashboard with a chat interface on the left and a graph/table view on the right. No special client software is required — Compass runs entirely in the browser.

Prerequisites: You need network access to the vitro.lan domain. If you are outside the cluster network, establish a VPN connection first.

The Chat Interface

The chat interface accepts natural language queries. Type your question and press Enter. Compass will either answer directly from the knowledge graph or route your query through the LLM for complex reasoning.

Direct Queries vs. LLM-Routed Queries

Not all queries go through the LLM. Compass uses two paths:

Query Type Path Speed Example
Template match Compass API queries FFO directly Instant (< 1s) “list clusters”, “show findings”
Natural language Compass API sends to LLM, LLM calls MCP tools 2-10 seconds “which clusters are missing FIPS compliance?”, “compare Ceph pool usage across clusters”

Template queries match known patterns and skip the LLM entirely. If your query matches a template, you will see results almost immediately. If it requires reasoning or multi-step tool calls, the LLM handles it and you will see a brief loading indicator.

Example Queries

Infrastructure Inventory

list all clusters

Returns a table of all Kubernetes clusters in the ontology with their attributes (name, environment, classification level, FIPS status, node count).

show nodes for cluster geo-prod-01

Returns all nodes belonging to a specific cluster, including node type, status, and resource capacity.

list all deployments

Returns deployments tracked in the ontology with their associated clusters and services.

Storage

show Ceph health

Returns the overall health status of Ceph clusters, including OSD counts, pool utilization, and monitor quorum status.

list Ceph pools

Returns all Ceph storage pools with their size, usage, and replication settings.

list OSDs

Returns all Ceph OSDs with their status (up/down, in/out) and host assignments.

Identity and Access

list users

Returns principals (users) tracked in the ontology with their roles and group memberships.

show roles for user jsmith

Returns IAM roles assigned to a specific user, including which groups grant those roles.

Security and Compliance

show findings

Returns security findings with severity, status, and associated entities (which cluster or deployment is affected).

list critical findings

Filters findings to show only those with critical severity.

what NIST controls apply to geo-prod-01?

Traverses the ontology from the cluster through its authorization boundary to find applicable NIST controls. This is an LLM-routed query that uses the ffo.traverse and ffo.context.for_action tools.

OpenStack and Kolla

list kolla services

Returns OpenStack services deployed via Kolla with their container status and health.

show VMs in project demo

Queries OpenStack Nova for virtual machines in a specific project.

Operations

show recent incidents

Returns incidents tracked in the ontology with their associated alerts and affected deployments.

show ArgoCD app status

Returns the sync status of ArgoCD-managed applications.

Reading Results

Table Format

Most query results are displayed as tables. Each row represents an entity, and columns correspond to attributes from the ontology.

name env class fips nodes
geo-prod-01 prod IL4 true 12
geo-staging-01 stage IL2 true 6
dev-cluster-01 dev IL2 false 3

Relationship Views

When you ask about relationships (“show nodes for cluster X”, “what controls apply to Y”), Compass displays the results as a connected graph on the right panel. You can:

  • Click nodes to see their full attributes
  • Drag nodes to rearrange the layout
  • Zoom in/out with the scroll wheel
  • Toggle between graph and table views

Empty Results

If a query returns no results, Compass will tell you explicitly. Common causes:

  • The entity name is misspelled (names are case-sensitive in TypeDB)
  • The entity type is wrong (“cluster” vs. “deployment”)
  • The data has not been synced to FFO yet

Query Tips

  1. Be specific about entity types. “list clusters” is better than “list everything.”
  2. Use the exact entity name. Names in FFO are case-sensitive. If you are unsure, start with a broad search: “search clusters with name containing geo”.
  3. Ask relationship questions naturally. “What controls apply to geo-prod-01?” works better than trying to construct a TypeQL query manually.
  4. Use the graph view for traversals. When exploring how entities connect, the graph visualization is more useful than the table view.
  5. Check Ceph entities use entity_name, not name. This is a schema convention in FFO. If a Ceph query returns empty results, verify you are using the correct attribute.

Troubleshooting

Compass is unreachable

Verify that the Compass pods are running:

kubectl get pods -n f3iai -l app=compass

Check that the Traefik IngressRoute is configured:

kubectl get ingressroute -n f3iai

Queries return errors

If you see a “TypeDB connection failed” error, the TypeDB pod may be down or the FFO MCP server cannot reach it:

kubectl get pods -n f3iai -l app=typedb
kubectl logs -n f3iai deployment/ffo-mcp-server --tail=50

Check the readiness endpoint:

curl -s https://compass.vitro.lan/api/ready | jq .

LLM queries are slow

LLM-routed queries take 2-10 seconds depending on complexity. If queries consistently exceed 10 seconds, check Ollama pod resources:

kubectl top pods -n f3iai -l app=ollama

Next Steps