Cognee

• In the Azure Portal, search the Marketplace for Cognee by SecureAnyCloud and select Create.
• Choose your subscription, resource group and region, and set the VM name.
• Select size Standard_B4ms, authentication type SSH public key, and paste your key.
• Under Inbound port rules, allow SSH (22) and HTTPS (443). Port 80 is optional and only redirects to HTTPS. Restrict the source of port 443 to your own network (see Security hardening).
• Leave the OS disk defaults, then select Review + create.

First boot takes about four minutes. It generates this VM's secrets and certificate and starts the services on the loopback address. It then loads the local model into memory (the model stays loaded, using about 5 GiB), proves that authentication is enforced, and only then opens nginx. If any part of that sequence fails, nothing is left listening.

Accept the Marketplace terms and create the VM. Replace the example resource group, VM name and key path with your own values.

az vm image terms accept --urn sac1647283583153:cognee-ubuntu-24-04:default:latest
az vm create \
  --resource-group my-resource-group \
  --name my-cognee-vm \
  --image sac1647283583153:cognee-ubuntu-24-04:default:latest \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard \
  --os-disk-delete-option Delete --nic-delete-option Delete

Then allow HTTPS from your own network only. Replace the example source range with your network:

az network nsg rule create \
  --resource-group my-resource-group \
  --nsg-name my-cognee-vmNSG \
  --name allow-https-from-office \
  --priority 1010 --access Allow --protocol Tcp \
  --destination-port-ranges 443 --source-address-prefixes 203.0.113.0/24

Connect to the VM over SSH:

ssh azureuser@<vm-ip>

Check that all seven units of the appliance are active:

• cognee-netguard: firewall rules for the services
• cognee-firstboot: per-VM secrets and the authentication proof
• ollama: the local model server, in its own private network namespace
• ollama-proxy.socket: the only door into the model server
• cognee: the API
• cognee-ui: the web interface
• nginx: HTTPS

systemctl is-active cognee-netguard cognee-firstboot ollama ollama-proxy.socket cognee cognee-ui nginx

Expected output:

active active active active active active active

Read the credentials file. Every VM generates its own credentials on first boot. Nothing is shared between instances and nothing is baked into the image.

sudo cat /root/cognee-credentials.txt

Expected output (your address and password will differ):

# cognee — per-VM credentials (generated at first boot on 2026-10-16T02:14:19Z) COGNEE_URL=https://20.42.14.78/ COGNEE_ADMIN_EMAIL=default_user@example.com COGNEE_ADMIN_PASSWORD=<unique per VM> COGNEE_LLM=bundled local model (Ollama, qwen2.5:7b-instruct-q4_K_M) — see the guide to switch to your own provider key

The sign-in name is the Cognee default account name, default_user@example.com. Its password is unique to this VM. The upstream default password default_password does not work, and first boot proves that before nginx opens.

Browse to https://<vm-ip>/. The certificate is self-signed and unique to this VM, so your browser shows a warning the first time. To confirm that you are connected to your own VM, compare the fingerprint your browser shows with the one on the VM:

openssl x509 -in /etc/ssl/certs/cognee-vm.crt -noout -fingerprint -sha256

Sign in with default_user@example.com and the password from Step 5. The sign-in form is prefilled with the Cognee default password, so replace it with yours.

After you sign in, the overview opens. Panels labelled "Cognee Cloud feature" link to the upstream project's separate hosted service. They are not part of this image, and nothing on the VM contacts that service.

Use the main pages as follows:

• Brain holds your datasets. Select New brain to create one and upload documents into it (text, Markdown, PDF and more). Cognee then builds the knowledge graph in the background.
• Search answers questions from a brain's graph and shows the evidence it used. Choose the brain with the selector above the question box.
• Mindmap draws the extracted entities and their connections.

Run the read-only self-check that ships with the image. Each probe is paired with a control so that a pass is meaningful. For example, the metadata service test first proves that root can reach the service, then proves that the application users cannot.

sudo cognee-selfcheck

Expected output:

PASS network listeners are exactly 22 80 443 PASS port 8000 bound to 127.0.0.1 only PASS port 3000 bound to 127.0.0.1 only PASS port 11434 bound to 127.0.0.1 only PASS port 11435 bound to 127.0.0.1 only PASS loopback listeners are exactly the UI, API, model gateway and model server (3000 8000 11434 11435) PASS port 80 only redirects to HTTPS (301) PASS anonymous API call refused (401) PASS upstream default password refused (400) PASS public self registration closed (403) PASS cognee (inside cognee.service) cannot reach IMDS or the WireServer PASS cognee-ui (inside cognee-ui.service) cannot reach IMDS or the WireServer PASS ollama (inside ollama.service) cannot reach IMDS or the WireServer PASS control: root reaches IMDS (200), so the blocks above are real PASS model server: gateway needs this VM's key (cognee w/o key 401), raw Ollama unreachable (cognee 000, nobody 000/000) PASS cognee app cannot reach loopback API/UI/TLS or private networks (control: root reaches the API, 200) SELFCHECK OK

The image enforces the following controls:

• Authentication. REQUIRE_AUTHENTICATION=true with Cognee's multi-user access control on. Every API route except /health refuses anonymous callers.
• No default password. Cognee 1.6 creates its default account without a password unless one is configured. First boot sets a unique password, proves that it signs in and that default_password is refused, then removes it from the configuration file.
• HTTPS only. nginx terminates TLS with a per-VM certificate, and port 80 only redirects. Session cookies are forced to Secure and HttpOnly.
• Closed registration. Public sign-up, password reset and email verification are closed at nginx (there is no mail server). Administrators add users from the VM itself (Step 12).
• Loopback only. The API (8000), web interface (3000) and model gateway (11434) listen on 127.0.0.1 only.
• Server-side request forgery protection. Cognee fetches URLs you give it. At the network layer, the cognee service account cannot reach the instance metadata service (169.254.169.254), the wire server (168.63.129.16), or private, shared or link-local networks. It also cannot reach anything on the loopback interface except the DNS resolver and the key-gated model gateway, so not the API, the web interface or the raw model server either. nftables enforces this per user and systemd enforces it per service, independently of the Cognee URL checks, so a hostname that resolves to an internal address, or a redirect to one, is refused too.
• Isolated model server. Ollama has no authentication of its own, so it runs in a private network namespace behind 127.0.0.1:11435, which only the gateway may open. The gateway on 127.0.0.1:11434 passes only requests that carry this VM's random LLM_API_KEY, and only the cognee service account (and root) may connect to it.
• Fail closed. The services refuse to start until first boot has written this VM's secrets, and nginx refuses to start until first boot has proven authentication.

Everything in the interface is also available over the REST API. Sign in once and keep the token in a file that only you can read. The command reads the password straight from the credentials file and passes it on standard input, so it never appears in a command line.

sudo sed -n 's/^COGNEE_ADMIN_PASSWORD=//p' /root/cognee-credentials.txt | tr -d '\n' \
  | curl -s --cacert /etc/ssl/certs/cognee-vm.crt https://127.0.0.1/api/v1/auth/login \
  --data-urlencode "username=default_user@example.com" --data-urlencode "password@-" \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])' > ~/.cognee-token chmod 600 ~/.cognee-token curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "Authorization: Bearer $(cat ~/.cognee-token)" \
  https://127.0.0.1/api/v1/users/me | python3 -c 'import json,sys; print(json.load(sys.stdin)["email"])'

Expected output:

default_user@example.com

Without a token the same call is refused:

curl -s -o /dev/null -w '%{http_code}\n' --cacert /etc/ssl/certs/cognee-vm.crt https://127.0.0.1/api/v1/users/me

Expected output:

401

For scripts and agents, create a long-lived key on the API Keys page and send it as the X-Api-Key header instead of a bearer token.

Create a short sample document and upload it to a dataset named quickstart:

cat > /tmp/northwind.txt <<'DOC' Northwind Analytics is a data consultancy founded in 2019 by Priya Raman in Leeds. Its flagship product is Lighthouse, a forecasting tool used by the Harbour Rail company. In 2024 Northwind opened a second office in Bristol, led by Tomas Ferreira. DOC curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "Authorization: Bearer $(cat ~/.cognee-token)" \
  -F "datasetName=quickstart" -F "data=@/tmp/northwind.txt" \
  https://127.0.0.1/api/v1/add | python3 -c 'import json,sys; print(json.load(sys.stdin)["status"])'

Expected output:

PipelineRunCompleted

Run cognify to read the document with the language model and build the graph. With the bundled CPU model this takes several minutes, so start it in the background:

curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "Authorization: Bearer $(cat ~/.cognee-token)" \
  -H 'Content-Type: application/json' -d '{"datasets":["quickstart"],"run_in_background":true}' \
  https://127.0.0.1/api/v1/cognify | python3 -c 'import json,sys; d=json.load(sys.stdin); print(sorted({v["status"] for v in d.values()}))'

Expected output:

['PipelineRunStarted']

Check progress at any time with the dataset status call:

curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "Authorization: Bearer $(cat ~/.cognee-token)" \
  https://127.0.0.1/api/v1/datasets/status

The value is DATASET_PROCESSING_STARTED while the graph is being built and DATASET_PROCESSING_COMPLETED when it is ready. Then ask a question. The command waits for completion first, and answering takes around a minute and a half on the bundled CPU model:

# ask-after-cognify H="Authorization: Bearer $(cat ~/.cognee-token)" for i in $(seq 1 12); do curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "$H" https://127.0.0.1/api/v1/datasets/status \
  | python3 -c 'import json,sys; d=json.load(sys.stdin); sys.exit(0 if d and all("COMPLETED" in v for v in d.values()) else 1)' && break sleep 5 done curl -s --cacert /etc/ssl/certs/cognee-vm.crt -H "$H" -H 'Content-Type: application/json' \
  -d '{"query":"Who founded Northwind Analytics, and in which city?","datasets":["quickstart"]}' \
  https://127.0.0.1/api/v1/search | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["search_result"][0])'

Expected output:

Priya Raman founded Northwind Analytics in Leeds.

The bundled model keeps everything on the VM. For faster processing and stronger answers, point Cognee at a hosted provider. Edit /etc/cognee/cognee.env (readable by root only) and replace the four LLM_ lines. Keep the local embedding settings unchanged, because changing the embedding model on a dataset that already has vectors requires rebuilding it.

For OpenAI, use:

LLM_PROVIDER=openai LLM_MODEL=openai/gpt-4o-mini LLM_ENDPOINT= LLM_API_KEY=<set-at-first-boot>

For Azure OpenAI, use an API key. Managed identity is not available because the application is deliberately blocked from the instance metadata service:

LLM_PROVIDER=azure LLM_MODEL=azure/your-deployment-name LLM_ENDPOINT=https://your-resource.openai.azure.com LLM_API_KEY=<set-at-first-boot> LLM_API_VERSION=2024-12-01-preview

If your provider endpoint has a private address on your own network (an Azure OpenAI private endpoint, or a model server on another VM), allow that address first, because the application is blocked from private networks by default. Add it to the cognee_private_allow set in /etc/cognee/netguard.nft (for example elements = { 10.1.2.3 }). Add a matching IPAddressAllow=10.1.2.3 with sudo systemctl edit cognee, then run sudo systemctl restart cognee-netguard.

Then restart the API:

sudo systemctl restart cognee

When you no longer use the local model, stop it to free memory with sudo systemctl disable --now ollama-proxy.socket ollama.

Public self-registration is closed. Create additional accounts from the VM itself, where the registration endpoint is still reachable on the loopback address:

curl -s -X POST http://127.0.0.1:8000/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"analyst@example.com","password":"<new-password>"}'

With multi-user access control on, each user sees only their own brains unless access is shared.

All Cognee data (accounts, documents, graph and vectors) lives under /var/lib/cognee. Stop the API and web interface to take a consistent copy:

sudo systemctl stop cognee cognee-ui
sudo tar czf /var/backups/cognee-backup.tar.gz -C /var/lib cognee
sudo systemctl start cognee cognee-ui ls -l /var/backups/cognee-backup.tar.gz | awk '{print $1, $3, $9}'

Expected output:

-rw-r--r-- root /var/backups/cognee-backup.tar.gz

Copy the archive off the VM, for example to Azure Blob Storage. To restore, stop the services, replace /var/lib/cognee with the archive contents (owned by cognee), and start the services again.

Read the API log:

sudo journalctl -u cognee -n 20 --no-pager

Use these commands for day-to-day operation:

• Restart the API: sudo systemctl restart cognee
• Restart the web interface: sudo systemctl restart cognee-ui
• Read the model server logs: sudo journalctl -u ollama -n 50
• Read the first-boot log: sudo journalctl -u cognee-firstboot
• Re-check security: sudo cognee-selfcheck

To see exactly what is installed and where it came from, read the provenance file:

cat /usr/share/cognee/PROVENANCE