Box CI

Box CI Agent

The Box CI agent is the open source tool you install on your hardware to run builds. It does all the work of coordinating with the Box CI service - all you have to do is run it.


> npm i -g boxci

This installs the Agent CLI globally as boxci on your build machine. Confirm the installation by running boxci --version.

The Agent CLI requires NodeJS to be present on your build machine to install and run. This is to support as many platforms as possible, as seamlessly as possible.


The Agent CLI has commands for starting/stopping agents, and managing local build history and logs on the machine.

boxci agent

Run an agent for a project.

Specify the project ID and secret key with the --project and --key options.

Each agent can run one build at a time for the specified project. You can run as many agents as you want on a single machine or across different machines.


Project's ID, accessible on the project page.


Project's secret key, accessible on the project page.

You can also set this option via the environment variable BOXCI_KEY=<key> if you prefer.


Name for the build machine. Shown on the build, so that you can see which builds this machine ran, if you wish.

You can also set this option via the environment variable BOXCI_MACHINE=<machine> if you prefer.


Do not show any console output.

You can also set this option via the environment variable BOXCI_SILENT=true if you prefer.


Use a different host for the project repository's ssh url on this build machine.

Useful if your build machine needs to configure different ssh keys for different repositories on the same host.

E.g. if your repository ssh url is but you need to make git ssh requests to to use the correct key, set --ssh-host

boxci stop <agent>

Gracefully stop a running agent.

An agent can be stopped manually by killing the process, but if it's in the process of running a build, that build will fail with a timeout. This command guarantees that won't happen by waiting for any builds in progress to complete before stopping the agent.


Name of the agent.

boxci history [mode]

View history of agents and builds run on this machine.


One of builds, projects, agents

builds lists history of all builds run on the machine.

projects lists history of all builds run on the machine, grouped by project

agents lists history of all builds run on the machine, grouped by agent

Leaving this option blank lists an overview of the numbers of builds, projects and agents in the history.

boxci logs <build>

Print the absolute path to the local log file for a build.

This command can be used in combination with tools to view and search your logs, such as tail, cat or your favourite text editor. See the examples for common usecases.


ID of the build.

boxci clean-logs

Clean logs of builds on this machine.

The options allow you to clean logs for a specific build, all builds for a project, or all builds period.

This command permanently deletes local log files from your build machine. This cannot be undone.

Be aware that the Box CI service stores its own copy of the logs, and running this command will not delete the logs there. The local log files are only stored for convenience, e.g. for auditing and easier debugging.

If you are deleting logs for security reasons, e.g. sensitive information leaked, ensure that you also delete the build logs on the Box CI service. This option can be found on the build page.

One required

A build ID.

Clear the logs of this build.


A project ID.

Clear the logs of all builds for this project.


Clears the logs of all builds on this machine.

boxci --version

Print the version of boxci

boxci --help

Print this documentation in the terminal.

Quick startDocsBlog