Skip to Content
HomeLocal DeploymentInstallLocal

Installing Arcade Locally

This guide will help you install Arcade and set up your development environment. If you are developing 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 : 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 , 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 locally, you’ll need to install arcade-engine. Choose the installation method that matches your operating system.

This will install a template engine configuration.

brew install ArcadeAI/tap/arcade-engine

Install a MCP Server

In order to run the Arcade , you’ll need to install at least one . 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 , see the Toolkit Installation page.

To see all available , view the MCP Servers Page.

Set OpenAI API key

Before starting the Engine, we need to set an OpenAI 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 and how to locate the engine.env file.

Start the Engine and worker

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

  1. First, start the :
arcade serve
  1. Then, start the engine:
arcade-engine

The Engine and 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 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

Troubleshooting

Engine Binary Not Found

❌ Engine binary not found

or

command not found: arcade-engine

This means that the 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 Servers found in the same environment as the Arcade SDK. Ensure that you are installing the 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.

or

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.

Last updated on
OverviewDocker