Installing Arcade AI Locally

This guide will help you install Arcade AI and set up your development environment.

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 AI Account: Sign up for an Arcade AI account (opens in a new tab) 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 engine, we need to install the ArcadeAI Client.

pip install 'arcade-ai[fastapi,evals]'
arcade login

For a simple example on using the client, see the quickstart.

Install the Engine

To run the Arcade AI engine locally, you need to install the 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 toolkit

In order to run the arcade actor, we need to install a tool. For local development, we can just pip install a tool in the same environment as the client.

pip install arcade-math

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

To see all available toolkits, view the Integrations 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.

export OPENAI_API_KEY="<your_openai_api_key>"

To make the API key persistent or to change other configurations, see the Configuration Overview.

Start the Engine and Actor

To run both the engine and a local actor, use:

arcade dev

The Engine and Actor should both be running locally now.

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

arcade-engine

Note that the Engine requires connection to at least one actor to run. Running the engine on it's own should only be used if external actors are available.

Connect

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

arcade chat -h localhost

You should now be chatting with your local Arcade setup. To see an example of chatting, view the quickstart.

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

Toolkits Not Found

No toolkits found in Python environment. Exiting...

This means that there are no toolkits found in the same environment as the Arcade Client. Ensure that you are installing the toolkit package in the same environment and see the Toolkit 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

arcade dev will search for the engine config in known directories including:

$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 without arcade dev, 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.

Overview Docker