Skip to main content

Check out Port for yourself 

Set up Port's n8n custom node

Port provides a custom n8n node (n8n-nodes-portio) that simplifies integration with Port's AI agents and API. Instead of making manual HTTP requests for authentication, invocation, and response retrieval, the Port node handles all of this automatically, making it easy to build powerful automation workflows that leverage Port's Context Lake.

This guide walks you through installing and configuring Port's custom n8n node in your n8n instance.

Prerequisites​

Before you begin, ensure you have:

  • pnpm installed — Required for building the custom node. Install pnpm if you don't have it.
  • A working n8n instance — Either n8n Cloud or a self-hosted instance. If you don't have one, follow n8n's guide on using Docker.
  • Port API credentials — Your Port Client ID and Client Secret. Learn how to get them.
  • A Port account with AI features enabled — Required for using Port AI agents in your workflows.

Set up n8n instance​

If you don't have an n8n instance running, you can set one up using Docker. The location where you mount the n8n data directory is important; this is where you will clone the Port n8n node code.

Using Docker (bind mount)​

Using a bind mount allows the container to read/write directly to your local filesystem, making it easier to work with the custom node code.

  1. Create a directory for n8n data (we will call this $n8n_HOME):

    mkdir -p ~/n8n-data

  2. Run n8n with a bind mount:

    docker volume create n8n_data

    docker run -it --rm \
      --name n8n \
      -p 5678:5678 \
      -e GENERIC_TIMEZONE="Africa/Accra" \
      -e TZ="Africa/Accra" \
      -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
      -e N8N_RUNNERS_ENABLED=true \
      -v ~/n8n-data:/home/node/.n8n \
      docker.n8n.io/n8nio/n8n
    Timezone configuration

    Replace "Africa/Accra" with your preferred timezone. The GENERIC_TIMEZONE and TZ environment variables should match.

    Bind mount path

    Replace ~/n8n-data with the actual local path you want to use such as /Users/janedoe/n8n-data. Anything n8n writes to /home/node/.n8n (inside the container) will persist directly to your local directory.

  3. Access n8n — Open your browser and navigate to http://localhost:5678.

Using Docker Compose​

If you prefer using Docker Compose, create a docker-compose.yml file:

version: '3'
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - GENERIC_TIMEZONE=Europe/Madrid
      - TZ=Europe/Madrid
    volumes:
      - ./n8n-data:/home/node/.n8n

Then run:

# Navigate to the directory containing your docker compose file
cd /path/to/your/compose/file/directory

# Pull latest version
docker compose pull

# Start the container
docker compose up -d

Install Port's n8n node​

Now that you have n8n running, let's install Port's custom node.

Clone the repository​

  1. Navigate to your n8n data directory (the $n8n_HOME directory you created earlier):

    cd ~/n8n-data

  2. Create the custom nodes directory (if it doesn't exist):

    mkdir -p custom
    cd custom

  3. Clone the Port n8n nodes repository:

    git clone https://github.com/port-labs/port-n8n-nodes.git
    cd port-n8n-nodes

Build the node​

  1. Install dependencies:

    pnpm install

  2. Build the TypeScript code:

    pnpm build

    If the build is successful, you will see a dist directory created.

  3. Restart your n8n instance:

    • If using Docker: Stop the container (Ctrl+C or docker stop n8n) and start it again with the same command.
    • If using Docker Compose: Run docker compose restart.
    Restart required

    n8n needs to be restarted after installing custom nodes so it can discover and load them.

Quick start​

Now that the Port node is installed, let us verify it works by creating a simple workflow.

Add a Port node to your workflow​

  1. Create a new workflow in your n8n instance.

  2. Add a trigger — For testing, add a Manual Trigger node so you can trigger the workflow manually by clicking the Execute Workflow button.

  3. Add the Port node:

    • Click the + button on the left side of the screen to add a new node
    • Search for port in the node search

  4. Select a Port node — Click the "Port.io" search result and select "General Purpose AI Interaction" (this is the easiest one to test with).

  5. Connect the nodes — Drag from the + icon on the trigger node to the left side of the Port AI node to connect them.

    Success!

    You have successfully deployed your first Port n8n node! The node is now available in your n8n instance.

Configure Port credentials​

Before you can use the Port node, you need to add your Port API credentials.

  1. Open the Port node — Double-click the Port AI node you just added.

  2. Create a new credential:

    • At the top of the node configuration, you will see a dropdown named Credential to connect with
    • Click this dropdown and select Create new credential

  3. Enter your Port credentials:

    • Client ID — Your Port Client ID
    • Client Secret — Your Port Client Secret
    Finding your credentials

    If you're not sure how to get your Port credentials, see the Port API documentation.

  4. Save the credential — Click "Save" to store the credential.

    Multiple credentials

    You can store multiple Port account credentials in n8n and select which one to use for each node. This is useful if you work with multiple Port organizations.

Verify the installation​

To verify everything is working:

  1. Configure the Port node — In the General Purpose AI Interaction node:

    • Select your Port credential from the dropdown
    • Enter a simple prompt like "List all ec2 instances in the eu-west region"
    • Save the node

  2. Execute the workflow — Click Execute Workflow to test the connection.

  3. Check the output — If successful, you should see the AI response in the node output.

What's next?​

Now that you have Port's n8n node installed and configured, you can:

  • Build automation workflows — Use Port's Context Lake to enrich your n8n workflows with organizational context
  • Integrate with AI agents — Invoke Port AI agents from n8n workflows
  • Query the catalog — Access service metadata, ownership, dependencies, and more

Troubleshooting​

Node not appearing in n8n​

  • Check the build — Ensure pnpm build completed successfully and created a dist directory
  • Verify the path — Make sure the repository is cloned in $n8n_HOME/custom/port-n8n-nodes
  • Restart n8n — Custom nodes are only loaded when n8n starts, so a restart is required

Credential errors​

  • Verify credentials — Double-check that your Client ID and Client Secret are correct
  • Check AI features — Ensure your Port account has AI features enabled
  • Test API access — Try making a direct API call to verify your credentials work