Neo4j setup

Create Context Graph supports four ways to connect to Neo4j. Choose the option that fits your workflow.

Neo4j Aura
Docker
neo4j-local
Existing instance

Neo4j Aura is a fully managed cloud graph database with a free tier. It requires no local installation and is the fastest way to get started.

Prerequisites

A Neo4j Aura account (free tier available)

Create an Aura instance

Go to console.neo4j.io.
Click New Instance.
Choose AuraDB Free (or a paid tier for production).
Select a region close to you.
Click Create.
Save the generated password — you need it in the next step.

Download the .env file

After the instance is created, click the Download .env button. The file contains your connection credentials:

NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-generated-password

Save this file somewhere accessible.

Scaffold your project

Pass the --neo4j-aura-env flag to import your Aura credentials directly:

uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --neo4j-aura-env /path/to/Neo4j-xxxxxxxx-Created-2026-03-28.txt \
  --demo-data

This parses the .env file, configures the generated project to use your Aura instance, and sets neo4j_type to aura automatically.

Verify the connection

cd my-app
make test-connection

You should see:

✅ Connected to Neo4j Aura (neo4j+s://xxxxxxxx.databases.neo4j.io)

Seed data and start

make install
make seed
make start

Connection refused

Ensure your Aura instance is Running (not paused).
Free-tier instances pause after 3 days of inactivity — resume from the Aura console.
Check that NEO4J_URI starts with neo4j+s:// (TLS is required for Aura).

Authentication failed

Double-check the password in your .env file.
If you lost the password, reset it from the Aura console under Instance settings.

Slow queries

Free-tier Aura instances have limited resources — queries may take 2–5 seconds. Upgrade to a paid tier for better performance.

The generated project includes a docker-compose.yml that runs Neo4j locally in a Docker container. This is the default setup when you don’t specify --neo4j-aura-env or --neo4j-local.

Prerequisites

Docker installed and running
Docker Compose (included with Docker Desktop)

Scaffold your project

uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --demo-data

By default, the generated project uses Docker for Neo4j with these settings:

NEO4J_URI=neo4j://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

Start Neo4j

cd my-app
make docker-up

This runs docker-compose up -d, which starts Neo4j on:

Bolt: localhost:7687 (driver connections)
Browser: localhost:7474 (Neo4j Browser UI)

Verify and seed

make test-connection  # Verify Neo4j is reachable
make seed             # Load demo data

Start the application

make install
make start

Managing the Neo4j container

# Stop Neo4j
make docker-down

# View logs
docker-compose logs neo4j

# Reset all data
make docker-down
docker volume rm $(docker volume ls -q | grep neo4j)
make docker-up

Neo4j data is stored in a Docker volume and persists across container restarts. Remove the volume as shown above to start fresh.

Neo4j Browser

While the container is running, open http://localhost:7474 to access the Neo4j Browser. Connect with:

Connect URL: neo4j://localhost:7687
Username: neo4j
Password: password

Port already in use

If port 7687 or 7474 is already in use, either stop the conflicting service or update the ports in docker-compose.yml.

Container won't start

Check Docker logs:

docker-compose logs neo4j

Common causes: insufficient memory (Neo4j needs at least 512 MB RAM) or file permission issues on the data volume.

@johnymontana/neo4j-local is an npm package that downloads and runs Neo4j Community Edition directly on your machine. It requires Node.js but no Docker installation.

Prerequisites

Node.js 18+

Start neo4j-local

You can start Neo4j before scaffolding:

npx @johnymontana/neo4j-local

This starts Neo4j on the default ports:

Bolt: neo4j://localhost:7687
Browser: http://localhost:7474

Default credentials: neo4j / neo4j (you will be prompted to change the password on first login).

Scaffold your project

Pass the --neo4j-local flag to configure your project for local Neo4j:

uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --neo4j-local \
  --demo

Start Neo4j via the Makefile target

The generated project also includes a make neo4j-start target that wraps the same npm package:

cd my-app
make neo4j-start

Seed and start

make install
make seed
make start

You can also configure the connection manually by setting these values in your .env file:

NEO4J_URI=neo4j://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Port already in use

If port 7687 is busy, another Neo4j instance may already be running. Stop it first or change the port.

Authentication failed

If you get auth errors after changing the password:

Stop Neo4j.
Delete the data directory (usually ~/.neo4j-local/data/).
Restart — you will get the default credentials again.

Connection refused

Neo4j may take 10–30 seconds to fully start on first launch while it initializes the database. Wait and retry.

Connect to any running Neo4j instance — a self-hosted server, Neo4j Desktop, or a single Docker container — by providing the URI directly.

Gather your connection details

You need:

URI — e.g., neo4j://localhost:7687 or neo4j+s://host:7687 for TLS
Username — typically neo4j
Password — the password you set when creating the instance

Scaffold with --neo4j-uri

uvx create-context-graph my-app \
  --domain healthcare \
  --framework pydanticai \
  --neo4j-uri neo4j://localhost:7687 \
  --neo4j-username neo4j \
  --neo4j-password your-password \
  --demo-data

You can also set these as environment variables and omit the flags:

export NEO4J_URI=neo4j://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=your-password

uvx create-context-graph my-app --domain healthcare --framework pydanticai --demo-data

Verify the connection

cd my-app
make test-connection

Seed and start

make install
make seed
make start

All four Neo4j connection options (--neo4j-aura-env, --neo4j-local, --neo4j-uri, and the default Docker path) produce the same generated project structure. Only the .env values and neo4j_type setting differ.

Get Started

Guides

Concepts

Prerequisites

Prerequisites

Managing the Neo4j container

Neo4j Browser

Prerequisites

​Prerequisites

​Prerequisites

​Managing the Neo4j container

​Neo4j Browser

​Prerequisites

Prerequisites

Prerequisites

Managing the Neo4j container

Neo4j Browser

Prerequisites