# n8n integration This guide walks you through the installation and running of custom Toolhouse nodes in n8n, enabling you to call Toolhouse agents within n8n workflows. This guide assumes you have the latest versions of Docker and Node.js installed in your environment. ### Installation First, set up a new folder to store your n8n instance. Run these commands in the terminal: ```bash git clone ``` Change the directory: ```bash cd toolhouse-n8n ``` Then run: ```bash npm install ``` **Note:** Make sure you have Node.js installed and updated to at least v16. ```bash npm run build ``` After that, make sure you have Docker open on your desktop and run: ```bash docker compose up ``` A successful run will look like this:
You will now be able to access n8n at . If the run fails, ensure Docker is open and running the correct container. Your Docker Desktop should look like this:
### Using n8n Your landing page should look like this:
### Create Credentials To use Toolhouse agents in your workflows, you'll need to connect your Toolhouse account. From the sidebar, select **Credentials** > **Add Credential**.
You will need a Toolhouse API key. To get your API key, go to [Toolhouse API Keys](https://app.toolhouse.ai/settings/api-keys) and either: * Copy an existing key, or * Click **Generate New Key**
Paste your API key into the appropriate field in the n8n node configuration, and then click **Save** to apply the changes.
You're now ready to use **Toolhouse Nodes** in your workflows! #### Starting a Toolhouse Agent Conversation on Workflow Execution Here is an example workflow using Custom Toolhouse Nodes. ### Add a Trigger Node Start your workflow with a trigger node. In this example, use the **Manual Trigger** node, which enables you to launch the workflow by clicking **Execute Workflow**.
### Add the **Toolhouse Node** Add the **Toolhouse Agent Node** to your flow. You can use this node to: * **Start a new conversation**, or * **Continue an existing one** by providing the `agentId` and the previous `agentRunId`. This allows your workflow to pick up where a previous interaction left off.
After selecting **Start Conversation** in the Toolhouse Node, your flow should resemble the following structure:
To choose an agent, open the **Toolhouse Node** and use the dropdown menu to select the agent you want to use in this workflow. If no agents are found: 1. Reopen your credentials 2. Confirm your Toolhouse API key is valid This is where all of your **Toolhouse agents** will appear. If you haven’t created any agents yet, please follow our [Quickstart Guide](https://docs.toolhouse.ai/toolhouse/quick-start-for-vibe-coders) to get started quickly and learn how to set up your first agent. ### Executing the Flow When you click **“Execute Workflow”**, this flow will initiate a **conversation with your Toolhouse agent**. ### **Using Webhooks** You can use webhooks to trigger your n8n workflows automatically from Toolhouse agents. > Prerequisite: Make sure you have an active Ngrok account, as it will be used to expose your local n8n instance to the internet. Once configured, your Toolhouse agent will be able to call this webhook and trigger your n8n automation in real time. #### Step 1: Open your n8n instance in the browser. Create a new **Webhook** node in your workflow.
Then, navigate to the **Production URL**.
You’ll need the **Production URL** of your webhook — this is the URL that Toolhouse agents will call. For example: ```bash ``` > Make sure you're using the Production URL (not the Test URL) from the webhook node in n8n. Next, expose your local n8n instance using Ngrok by running: ```bash ngrok http 5678 ``` This will create a public URL that forwards to your local `localhost:5678`, allowing Toolhouse agents to trigger your workflows remotely. This is what your terminal should look like after running Ngrok:
Copy the first **Forwarding** link (the `https` one). In this example: ### Scheduling your agents Now you’ll create the **callback URL** that Toolhouse agents will use. Take your **Production URL** from n8n (e.g.): ```bash ``` Replace the `localhost:5678` portion with your Ngrok forwarding domain. **Example callback URL:** ```bash ``` Use this full URL when setting up your Toolhouse agent’s webhook. ### Using Toolhouse Schedules Now, you’ll set up schedules that determine when your agents should run. These schedules will remotely call the webhook URL you configured, triggering your n8n workflow at the specified times.
To create a new schedule, follow these steps: 1. Navigate to . 2. Click **New Schedule** in the top right corner. This will open schedule creation, where you can configure how often your agent should run and which webhook it should call.
Next, choose the agent you want to schedule from the dropdown. > Note: If you don’t have any agents yet, you can create one at . Once you've selected an agent, continue configuring the schedule details.
Then, choose a **cadence** — this defines how often the agent should run (e.g., every 5 minutes, hourly, daily). After setting the cadence, enter the **Callback URL** you created earlier. This is the public webhook URL exposed by Ngrok, which will trigger your n8n workflow.
### Completed Example Here’s a completed example using this callback URL we generated earlier: ``` ``` Once you've filled out all the fields, click **Create Schedule**. Your agent is now scheduled! When the schedule runs, it will call the webhook and trigger your n8n workflow automatically. ### Next steps **You're All Set! Your n8n instance is now fully connected to Toolhouse agents.** You can go ahead and build your own workflows with Toolhouse and n8n. Happy Building! Need help? Visit [Toolhouse Support](http://help.toolhouse.ai) or ask in our [Community Discord](https://discord.gg/2Pfsz6b6). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.toolhouse.ai/toolhouse/integrations/n8n-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.