Getting Started

Get Arc up and running in 5 minutes.

Prerequisites

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

Quick Start

Docker
Kubernetes
Debian/Ubuntu
RHEL/Fedora

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
Kubernetes
Native (systemd)

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

MessagePack (18M+ rec/s)
Line Protocol
Python SDK

import msgpack
import requests
from datetime import datetime
import os

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

# InfluxDB 1.x compatible endpoint
curl -X POST "http://localhost:8000/write?db=default&p=$ARC_TOKEN" \
  --data-binary "cpu,host=server01 usage_idle=95.0,usage_user=3.2"

# Or with Authorization header
curl -X POST "http://localhost:8000/write?db=default" \
  -H "Authorization: Bearer $ARC_TOKEN" \
  --data-binary "cpu,host=server01 usage_idle=95.0,usage_user=3.2"

from arc_client import ArcClient

with ArcClient(host="localhost", token=os.environ["ARC_TOKEN"]) as client:
    client.write.write_columnar(
        measurement="cpu",
        columns={
            # numeric epoch in microseconds (2024-01-01 00:00:00 UTC)
            "time": [1704067200000000],
            "host": ["server01"],
            "usage_idle": [95.0],
        },
    )

Query Data

curl
Python
Arrow (6M+ rows/s)

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"}'

import requests
import os

token = os.getenv("ARC_TOKEN")

response = requests.post(
    "http://localhost:8000/api/v1/query",
    headers={"Authorization": f"Bearer {token}"},
    json={"sql": "SELECT * FROM default.cpu LIMIT 10", "format": "json"}
)

print(response.json())

import requests
import pyarrow as pa
import os

token = os.getenv("ARC_TOKEN")

response = requests.post(
    "http://localhost:8000/api/v1/query/arrow",
    headers={"Authorization": f"Bearer {token}"},
    json={"sql": "SELECT * FROM default.cpu LIMIT 10000"}
)

reader = pa.ipc.open_stream(response.content)
df = reader.read_all().to_pandas()
print(df.head())

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
Kubernetes
Native

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"

Prerequisites​

Quick Start​

Get Your Admin Token​

Write Data​

Query Data​

Next Steps​

Troubleshooting​

Common Issues​

Need Help?​