Getting Started

Run Arc for the first time with Docker, Helm, or a native package, read the first-run admin token from the logs, write a measurement, and query it back over SQL.

Get Arc up and running in 5 minutes.

Prerequisites

4GB RAM minimum, 8GB+ recommended
Docker, Kubernetes, or Linux (Debian/RHEL)

Quick start

docker run -d \
  --name arc \
  -p 8000:8000 \
  -v arc-data:/app/data \
  ghcr.io/basekick-labs/arc:latest

Verify it's running:

curl http://localhost:8000/health

Get your admin token

Arc generates an admin token on first startup. Copy it immediately - you won't see it again!

docker logs arc 2>&1 | grep -i "admin"

You'll see:

======================================================================
  FIRST RUN - INITIAL ADMIN TOKEN GENERATED
======================================================================
  Initial admin API token: arc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
======================================================================

Save it:

export ARC_TOKEN="arc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Write data

import msgpack
import requests
from datetime import datetime
import os

ARC_TOKEN = os.environ["ARC_TOKEN"]

token = os.getenv("ARC_TOKEN")

data = {
    "m": "cpu",
    "columns": {
        # time must be a numeric Unix epoch (microseconds recommended).
        # Strings (e.g. "2024-01-01T00:00:00Z") and nulls are rejected.
        "time": [int(datetime.now().timestamp() * 1_000_000)],
        "host": ["server01"],
        "usage_idle": [95.0],
        "usage_user": [3.2]
    }
}

response = requests.post(
    "http://localhost:8000/api/v1/write/msgpack",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/msgpack",
        "x-arc-database": "default"
    },
    data=msgpack.packb(data)
)

Query data

curl -X POST http://localhost:8000/api/v1/query \
  -H "Authorization: Bearer $ARC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM default.cpu LIMIT 10", "format": "json"}'

Next steps

Python SDK - Official client with DataFrame support
Telegraf Integration - Collect system metrics
Apache Superset - Build dashboards
Configuration - Tune Arc for your workload

Troubleshooting

docker logs arc

Common issues

Authentication errors: Make sure ARC_TOKEN is set and included in headers.

No data returned: Data may not be flushed yet. Force flush:

curl -X POST http://localhost:8000/api/v1/write/line-protocol/flush \
  -H "Authorization: Bearer $ARC_TOKEN"