Installing Arcade Locally

This guide will help you install Arcade and set up your development environment. If you are developing tools to use with Arcade, this guide will provide you with a complete local deployment of Arcade for developing and testing tools.

Prerequisites

Before you begin, make sure you have the following:

Python 3.10 or higher
pip: The Python package installer should be available. It’s typically included with Python.
Arcade Account: Sign up for an Arcade account if you haven’t already.
Package Manager: Either Brew (macOS) or Apt (linux) to install the engine binary.

Verify your Python version by running python --version or python3 --version in your terminal.

Installation

Install the Client

To connect to the cloud or local Arcade Engine, we need to install the Arcade CLI from the arcade-ai package.


pip install arcade-ai
arcade login

For a simple example on using the Arcade CLI, see the quickstart on building tools

Install the Engine

To run the Arcade Engine locally, you’ll need to install arcade-engine. Choose the installation method that matches your operating system.

This will install a template engine configuration.

macOS (Homebrew)


brew install ArcadeAI/tap/arcade-engine

Ubuntu/Debian (APT)


wget -qO - https://deb.arcade.dev/public-key.asc | sudo apt-key add -
echo "deb https://deb.arcade.dev/ubuntu stable main" | sudo tee /etc/apt/sources.list.d/arcade-ai.list
sudo apt update
sudo apt install arcade-engine

Windows (coming soon)


Windows support is coming soon!

Want to see Windows support sooner? Show your interest by adding a 👍 to this GitHub issue .

Install a MCP Server

In order to run the Arcade worker, you’ll need to install at least one tool. For local development, you can just pip install a tool in the same environment as the client.


pip install arcade-math

For more information on installing tools, see the Toolkit Installation page.

To see all available tools, view the MCP Servers Page.

Set OpenAI API key

Before starting the Engine, we need to set an OpenAI API Key that the Engine can use to connect to OpenAI.

Edit the engine.env file to set the OPENAI_API_KEY environment variable:


OPENAI_API_KEY="<your_openai_api_key>"

See the configuration overview for more information on how to configure Arcade Engine and how to locate the engine.env file.

Start the Engine and worker

To run both the engine and a local worker, follow these steps:

First, start the worker:


arcade serve

Then, start the engine:


arcade-engine

The Engine and worker should both be running locally now.

To run the Engine on it’s own, you can run:


arcade-engine

Note that the Engine requires at least one Arcade worker to run.

Connect

To chat with the running Engine, in a separate terminal instance, run:


arcade chat -h localhost

You are now chatting with Arcade locally!

Next Steps

Building Tools: Learn how to build tools with your local Arcade Instance in the Creating a Toolkit guide.
Hosting With Docker: Learn how to run the Engine in Docker.

Troubleshooting

Engine Binary Not Found


❌ Engine binary not found


command not found: arcade-engine

This means that the Arcade Engine cannot be found in your path. Brew and Apt will automatically add the binary to you path.

Check that the binary has been properly installed (These are the common installation locations):

Brew


ls $HOMEBREW_REPOSITORY/Cellar/arcade-engine/<version>/bin/arcade-engine

Apt


ls /usr/bin/arcade-engine

If the binary is found, add it to your path with:


export PATH=$PATH:/path/to/your/binary

MCP Servers Not Found


No toolkits found in Python environment. Exiting...

This means that there are no MCP Servers found in the same environment as the Arcade SDK. Ensure that you are installing the MCP Server package in the same environment and see the MCP Server Installation Guide for more details.

Engine Config Not Found


❌ Config file 'engine.yaml' not found in any of the default locations.


Arcade Engine has finished with error: unable to read config file $HOME/.arcade/engine.yaml: open $HOME/.arcade/engine.yaml: no such file or directory

The engine config may be located in one of the following directories:

$HOME/.arcade/engine.yaml
$HOMEBREW_REPOSITORY/etc/arcade-engine/engine.yaml (Homebrew)
/etc/arcade-ai/engine.yaml (Apt)

The engine config will be downloaded by and added to one of these locations when installing the engine.

When running the engine, the config needs to be in the $HOME/.arcade/ directory or explicitly located with arcade-engine -c /path/to/engine.yaml.

If you cannot find your engine config, you can save and use the Configuration Templates.