Skip to main content
This guide walks you through building Arcentra from source, starting the control plane, and connecting your first agent.

​
Prerequisites

  • Go 1.25 or later (matches go.mod)
  • MySQL 8.x (or SQLite for single-node experiments)
  • Redis 6.x or later
  • Kafka for the default event and log pipeline
  • Optional: Docker for containerized builds and runs

​
1. Get the source

git clone https://github.com/arcentrix/arcentra.git
cd arcentra

​
2. Build the binaries

The Makefile drives code generation (Buf and Wire) and binary builds. 
make deps
make build TARGET=arcentra
make build TARGET=arcentra-agent
After a successful build you should see two binaries in the project root: arcentra (control plane) and arcentra-agent (agent).
Run make help to list all available targets, including lint, test, codegen, docker-build, and docker-buildx.

​
3. Configure the control plane

Arcentra ships with example configuration files under conf.d/:
  • conf.d/config.toml — control plane (HTTP, gRPC, database, Redis, Kafka, tracing, JWT).
  • conf.d/agent.toml — agent configuration (gRPC client, sandbox, labels).
  • conf.d/plugins.toml — plugin and builtin defaults (Git, SVN, shell, etc.).
Edit conf.d/config.toml to point at your environment. At minimum you should review:
  • [http] and [grpc] listen addresses (defaults: :8080 and :9090)
  • [database.mysql].dsn (or switch driver to sqlite)
  • [redis].address
  • [messageQueue.kafka].bootstrapServers and SASL credentials
  • [http.auth].secretKey (rotate this for any non-local deployment)

​
4. Run the control plane

./arcentra -conf conf.d/config.toml -plugin-conf conf.d/plugins.toml
The -conf flag points at the main control-plane configuration; the -plugin-conf flag points at plugin and builtin defaults. Both default to the files under conf.d/ if omitted. You should see HTTP serving on port 8080, gRPC on 9090, and the metrics endpoint on 8082 (defaults from config.toml).

​
5. Run an agent

In a second shell, start the agent: 
./arcentra-agent -conf conf.d/agent.toml
Update the following before connecting an agent to a real cluster:
  • [grpc].serverAddr and [grpc].token so the agent can reach the control plane.
  • [agent].mode (sandbox or baremetal) and [agent.sandbox] settings if you run jobs in containerd or Kubernetes.
  • [agent.labels] to expose scheduling attributes such as env, team, or region.

​
6. Verify the deployment

  • Visit the metrics endpoint: http://<host>:8082/metrics.
  • Check the control plane logs for agent registration entries.
  • Trigger a pipeline using the HTTP API; see Pipelines and the API reference.

​
Next steps

Architecture

Learn how the control plane, agents, and pipeline runtime fit together.

Configuration

Reference every section of config.toml, agent.toml, and plugins.toml.

Pipelines

Author and run pipelines via DSL and HTTP APIs.

Development

Generate code, lint, test, and tag releases.
Last modified on April 26, 2026