Before we dive in, one quick heads-up:
This guide is for local development and testing only. It is not a production setup. By the end of this tutorial, you will have n8n running privately on your own computer — not exposed to the internet, not connected to a domain, just a clean local environment where you can learn, experiment, and build freely.
If you want to run n8n publicly for real work, that requires a separate setup with HTTPS, a domain, a production database, backups, and more. I’m working on a guide for that too. But that’s not what this is.
This is the “get it running and start playing” guide.
What You’re Actually Building
By the time you finish this tutorial, you’ll have n8n running at:
http://localhost:5678
You’ll be able to open that in your browser, create a local account, and start building workflows. That’s it. Simple, contained, and completely safe to experiment with.
Why Bother With a Local Setup?
If you’re new to n8n, setting it up manually can feel like a lot. You run into Docker commands, port numbers, terminal errors, missing dependencies, and confusing instructions — and all you wanted to do was try building an automation.
That’s where Codex comes in.
Instead of writing every setup file yourself and debugging each step alone, you give Codex a clear prompt and let it handle the boring parts. It creates the files, runs the commands, and checks that things are working. You stay in control, but without all the friction.
Less time fighting setup. More time actually learning n8n.
What You Need Before You Start
Check that you have these ready before doing anything else.
Docker Desktop
This is the engine that runs n8n in a container on your machine. Download it at docker.com/products/docker-desktop. Once it’s installed, make sure it’s actually open and running — you’ll usually see the Docker whale icon in your system tray or menu bar. If Docker isn’t running, nothing else will work.
Docker Compose
This usually comes bundled with Docker Desktop. To confirm it’s there, open your terminal and run:
docker compose version
If you see a version number, you’re good.
Node.js and npm
You’ll need these if you want to install the Codex CLI or eventually build custom n8n nodes. Check whether they’re installed:
node -v
npm -v
Both commands should return a version number. If they don’t, download Node.js at nodejs.org — the LTS version is the safe choice for most people.
Git
Git helps you manage your project folder and save checkpoints before Codex makes changes. Check it with:
git --version
If it’s not installed, grab it at git-scm.com.
Codex
You can use either the Codex desktop app or the CLI. For the CLI, install it with:
npm i -g @openai/codex
Then start it by typing codex in your terminal. The first time you run it, it may ask you to sign in. For the desktop app, download it from OpenAI’s website and sign in with your ChatGPT account.
A terminal
Use whatever feels comfortable — Windows Terminal, PowerShell, the VS Code terminal, macOS Terminal, or a Linux terminal all work fine. If you’re on Windows, Windows Terminal or the VS Code terminal are both great choices.
Step 1 — Create a Project Folder
First, create a clean folder where your local n8n setup will live. Open your terminal and run:
mkdir n8n-local-dev
cd n8n-local-dev
Your terminal prompt should now show that you’re inside the n8n-local-dev folder. On Windows it might look like C:\Users\YourName\n8n-local-dev> and on Mac or Linux something like ~/n8n-local-dev $.
That’s your workspace. Everything Codex creates will go in here.
Step 2 — Open Codex in That Folder
From inside that same folder, start Codex:
codex
If you’re using the desktop app instead, open it and point it to the n8n-local-dev folder as your workspace.
Quick sanity check: Before giving Codex the main setup prompt, ask it to create a small test file first:
Create a file called test.txt with the text: n8n local setup test
Then check whether the file actually appeared in your folder. If it did, Codex is working in the right place and you’re ready to go. If it didn’t, something is off with your workspace setup — fix that before moving on.
Step 3 — Give Codex the Setup Prompt
This is the heart of the whole process. Copy the prompt below and paste it into Codex exactly as written. You can change the folder path and the custom node name to match your setup, but keep everything else the same.
You are helping me set up a local self-hosted n8n development environment
on my Windows PC using Docker Desktop.
Current local project folder:
D:\projects\n8n-local-dev
Purpose:
This n8n instance is for local development and testing only.
It is not for public production hosting.
Please create the following files and folders:
Files:
1. docker-compose.yml
2. .env.example
3. README.md
4. .gitignore
Folders:
1. custom-nodes
2. workspace
3. docs
Requirements for docker-compose.yml:
- Use the official n8n Docker image.
- Run n8n locally at http://localhost:5678
- Persist n8n data using a Docker named volume.
- Enable community packages.
- Configure n8n to load local custom nodes from a mounted custom-nodes folder.
- Keep the setup simple and appropriate for local development.
- Do not configure public hosting.
- Do not configure SSL.
- Do not configure a reverse proxy.
- Do not configure Postgres yet.
Use these environment variables:
- N8N_HOST=localhost
- N8N_PORT=5678
- N8N_PROTOCOL=http
- NODE_ENV=development
- N8N_COMMUNITY_PACKAGES_ENABLED=true
- N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom
Volume requirements:
- Persist n8n data using a named Docker volume.
- Mount the local ./custom-nodes folder into /home/node/.n8n/custom
inside the container so custom nodes can be tested later.
The README.md should include exact PowerShell commands for:
- starting n8n
- stopping n8n
- restarting n8n
- viewing logs
- checking container status
- resetting the local volume for a fresh install
- opening n8n in the browser
Troubleshooting section should cover:
- Docker Desktop not running
- WSL2 issues
- port 5678 already in use
- n8n container starts but browser does not load
- custom nodes not appearing
After creating the files, tell me the exact next PowerShell command
I should run.
Why is this prompt so detailed?
Because a vague prompt gets vague results. When you tell Codex exactly what you want — the files, the folder structure, the environment variables, and importantly what not to include — it builds exactly what you need instead of going off and building a full production server when all you wanted was something running on your laptop.
That last part especially matters. By telling Codex “no SSL, no reverse proxy, no Postgres,” you’re keeping things simple and local.
Step 4 — Review What Codex Plans to Do
Codex will often describe what it’s about to do before it does it. Take a few seconds to read through the plan.
For this tutorial, the plan should be simple — create a few files, set up a Docker container, start it, and check it’s running. That’s all.
If Codex starts talking about Traefik, Caddy, PostgreSQL, SSL certificates, or public domains, stop it and say:
Keep this local development only. No production hosting, no SSL, no reverse proxy, no domain setup, no PostgreSQL.
Step 5 — Let Codex Create the Files and Start n8n
Codex will create your docker-compose.yml and supporting files, then run:
docker compose up -d
Here’s what that command actually means in plain English:
docker compose— use the setup file we just createdup— start everything-d— run it in the background so your terminal stays free
The first time you run this, Docker will download the n8n image from the internet. That can take a minute or two depending on your connection. You’ll see it downloading — that’s normal, just let it finish.
Your docker-compose.yml will look something like this:
services:
n8n:
image: n8nio/n8n:stable
restart: unless-stopped
ports:
- "5678:5678"
environment:
- GENERIC_TIMEZONE=Africa/Accra
- TZ=Africa/Accra
- N8N_COMMUNITY_PACKAGES_ENABLED=true
volumes:
- n8n_data:/home/node/.n8n
- ./custom-nodes:/home/node/.n8n/custom
volumes:
n8n_data:
If your timezone is different, just ask Codex to change it:
Change the timezone to America/New_York
Step 6 — Confirm n8n Is Running
Once Codex finishes, check that the container is actually up:
docker ps
You should see a running container using the n8nio/n8n image, with port 5678 listed. You can also open Docker Desktop and click Containers — your n8n container should appear there with a green “running” status.
Step 7 — Open n8n in Your Browser
Go to:
http://localhost:5678
If this is your first time, n8n will ask you to create a local owner account — just a name, email, and password. Use whatever you like, since this is only for your local machine. Nobody else can access it.
After that, you’ll land inside the n8n editor. You’ll see a blank workflow canvas and a navigation menu. That’s it — you’re in.
Step 8 — Test That Everything Works
Before you declare victory, run a quick test to make sure n8n is actually working properly.
Click Create Workflow, add a Manual Trigger node, then add a Set or Edit Fields node after it. Add a simple field like:
message = Local n8n is working
Click Execute Workflow. If it runs successfully and shows your message in the output, everything is working correctly.
Stopping and Starting n8n
When you’re done for the day, stop n8n with:
docker compose down
This stops the container, but your workflows and data are safely saved in the Docker volume. They’ll be there when you come back.
To start n8n again next time:
cd n8n-local-dev
docker compose up -d
Then open http://localhost:5678 and pick up where you left off.
When Things Go Wrong — Don’t Panic
Most issues with local Docker setups are very fixable. Here’s how to handle the common ones.
n8n won’t open in the browser
Check whether the container is running:
docker ps
If it’s not listed, start it again with docker compose up -d. If it still won’t start, check the logs:
docker compose logs n8n
Copy whatever error you see and ask Codex:
n8n didn’t start. Here’s the error from the logs: [paste it here]. Explain what went wrong in beginner-friendly terms and suggest the safest fix.
Docker says it can’t connect
This usually means Docker Desktop isn’t running. Open Docker Desktop, wait until it shows that Docker is running, then try again.
Port 5678 is already in use
Something else on your computer is using that port. Ask Codex:
Port 5678 is already in use. Help me find what’s using it and suggest a beginner-friendly fix.
A quick workaround is to change the port in your docker-compose.yml from 5678:5678 to 5679:5678, then open http://localhost:5679 instead.
You want to start completely fresh
Before running any commands to wipe things, ask Codex first:
I want to completely reset my local n8n setup. Explain what will be deleted, then give me the safest commands to stop the container and remove the Docker volume.
Be careful here — removing the Docker volume deletes all your local workflows and credentials. Only do this if you’re okay losing what’s there.
Handy Prompts to Keep Using
Once n8n is running, here are some useful things you can ask Codex:
Understand your setup:
Explain every file in this local n8n Docker setup in beginner-friendly language. Tell me what each setting does and what I should avoid changing.
Add a README:
Create a README.md for this local n8n setup with prerequisites, start and stop commands, the local URL, and beginner-friendly troubleshooting steps.
Keep it simple:
Review this local n8n Docker setup and tell me if anything is unnecessarily complicated for a development-only environment. Do not add production features.
Get workflow ideas:
Suggest a simple n8n test workflow that confirms my local instance is working. Keep it beginner-friendly and don’t require any paid services.
A Few Things to Keep in Mind
This local setup is great for learning, testing, and experimenting. It is not meant for:
- Hosting workflows that real clients or teams depend on
- Exposing to the internet
- Storing sensitive production credentials
- Replacing a properly configured production deployment
When you’re ready to move to production, that’s a different (and more involved) setup — but this local environment is the perfect place to learn before you get there.
Final Thought
The real win here isn’t that Codex knows Docker. It’s that Codex gets you past the setup friction so you can start doing the thing you actually came to do — building workflows.
For anyone new to n8n, that matters a lot. Spending your first two hours fighting a terminal instead of building your first automation is discouraging. Getting n8n running quickly means you start learning by doing, which is the fastest way to get good at this.
Start local. Keep it simple. Build something. Then when you’re ready, take it further.
Got stuck on a step or ran into an error not covered here? Drop it in the comments — let’s figure it out together.
thanks for sharing this; really nice guide.