> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcentra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build Arcentra, start the control plane, and connect an agent.

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

```bash theme={null}
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.

```bash theme={null}
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).

<Tip>
  Run `make help` to list all available targets, including `lint`, `test`,
  `codegen`, `docker-build`, and `docker-buildx`.
</Tip>

## 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

```bash theme={null}
./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:

```bash theme={null}
./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](/en/pipelines) and the
  [API reference](/en/api-reference/introduction).

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/en/architecture">
    Learn how the control plane, agents, and pipeline runtime fit together.
  </Card>

  <Card title="Configuration" icon="sliders" href="/en/configuration">
    Reference every section of `config.toml`, `agent.toml`, and `plugins.toml`.
  </Card>

  <Card title="Pipelines" icon="diagram-project" href="/en/pipelines">
    Author and run pipelines via DSL and HTTP APIs.
  </Card>

  <Card title="Development" icon="code" href="/en/development">
    Generate code, lint, test, and tag releases.
  </Card>
</CardGroup>