Set Up llamactl on Windows

Prerequisites

Package Manager

All installation scripts rely on Chocolatey as the package manager. You’ll need to install it first using a shell with administrator privileges.

To install Chocolatey, run the following commands from this folder:

.\scripts\powershell\install_choco.ps1
# Test the installation (you may need to open a new shell)
choco -v

Dependencies

While it may not be required for every Windows setup (depending on user permissions), it’s recommended to run installation scripts from an administrator shell.

To install and run llamactl successfully, make sure you have the following programs installed:

• Python (with pip)
• uv
• Node.js (with npm)
• Git

Optionally, you can also install corepack.

You can either use the scripts in scripts/installation/ to install specific dependencies or run the main setup script to install everything at once (note: this may take some time):

.\setup.ps1

Get Started with a Template

Since llamactl init uses symbolic links, it’s best to enable Developer Mode in PowerShell by running:

start ms-settings:developers

You’ll be prompted to enable Developer Mode in your system settings if it’s not already active.

Next, initialize your project:

llamactl init

For this example, select the basic UI template and save it as basic-ui.

Serve the Template Locally

Once you have your template, navigate into the project folder and start the local server:

cd basic-ui/
llamactl serve

Your application will be available at:
http://127.0.0.1:4501/deployments/app/ui/

Test the Backend

To verify the backend workflow, first test the health check and available workflows on your local server:

cd ..
.\scripts\test-backend\test_backend_basics.ps1

Then, try running the default workflow:

.\scripts\test-backend\test_backend_run.ps1

Deploy

To deploy, start from a clean directory: make sure you’re outside of this or any other Git repository.

Once there, you can repeat the init and serve steps to confirm everything works correctly.
Then, create a new GitHub repository named llamactl-test-deployment. When ready, link it as your remote:

git remote add origin https://github.com/<your-username>/llamactl-test-deployment

Add, commit, and push your local changes to the main branch:

git branch -M main
git add .
git commit -m "first commit"
git push -u origin main  # use --force if needed to bypass branch rules

Once your GitHub repository is set up, authenticate with LlamaCloud to deploy your agent.
The easiest way is to use your LlamaCloud API key and project ID:

llamactl auth token --project-id YOUR_LLAMA_CLOUD_PROJECT_ID --api-key YOUR_LLAMA_CLOUD_API_KEY --no-interactive

Finally, create the deployment:

llamactl deployments create

This will open a terminal interface prompting you to select your GitHub repository source and reference.
Make sure the source points to:

https://github.com/<your-username>/llamactl-test-deployment

and the reference is set to main.

Click Save to start the deployment.
If everything is configured correctly, your first application should appear on the Agents page of your LlamaCloud account within a few minutes!